cvs: phpdoc-ja /internals/zendapi arguments.xml

takagi Sun Jul 2 04:55:29 2006 UTC Added files: /phpdoc-ja/internals/zendapi arguments.xml Log: added Japanese translation.

http://cvs.php.net/viewvc.cgi/phpdoc-ja/internals/zendapi/arguments.xml?view=markup&rev=1.1 Index: phpdoc-ja/internals/zendapi/arguments.xml +++ phpdoc-ja/internals/zendapi/arguments.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <!-- EN-Revision: 1.3 Maintainer: takagi Status: ready --> <sect1 id="zend.arguments"> <title>引数の扱い</title> <para> 言語を拡張する際の最も重要な問題のひとつは、 引数として渡されるデータの扱いです。たいていの拡張モジュールは、 何らかの入力データを扱う (あるいはパラメータを受け取って 特定の動作を行う) ように作られています。そして、 PHP と C 言語の間でデータをやり取りするための唯一の方法が 関数の引数となります。 事前に定義したグローバル値を使用してデータを交換することももちろん可能ですが (この方法についても後述します)、いろんな意味でこの方法は避けるべきです。 これはまったくお勧めできない手段です。 </para> <para> PHP では、正式に関数を宣言 (declare) することはありません。 そのため、関数コールの構文は完全に動的なものとなり、 エラーチェックは行われません。 コール方法が正しいかどうかを調べるのは、ユーザが書くコードの役割となります。 例えば、ある関数に対して引数をひとつだけ指定してコールした後、 同じ関数に対して 4 つの引数を指定してコールすることも可能です。 どちらのコールについても、文法的にはまったく正しいものとなります。 </para> <sect2 id="zend.arguments.count"> <title>引数の数の定義</title> <para> PHP が正式な関数宣言を行わないためにコール時の文法チェックが行われない、 また PHP が可変引数をサポートしているなどの理由で、 実際にその関数にいくつの引数が渡されたのかを知らなければならないこともあるでしょう。 そのような場合には <literal>ZEND_NUM_ARGS</literal> マクロを使用します。 以前のバージョンの PHP では、コール時の引数の数を取得するために このマクロは関数のハッシュテーブルのエントリ <envar>ht</envar> を使用していました。このエントリは <literal>INTERNAL_FUNCTION_PARAMETERS</literal> のリストから渡されました。 関数に渡された引数の数は今では <envar>ht</envar> 自体に含まれているので、<literal>ZEND_NUM_ARGS</literal> はダミーのマクロとなっています (実際の定義は <filename>zend_API.h</filename> を参照ください)。 しかし、今後のことを考えると、 呼び出しインターフェイスが変わっても互換性を保ち続けられるように このマクロを使用しておくことをお勧めします。 <emphasis>注意:</emphasis> 昔の PHP では、このマクロと同等の働きをするのは <literal>ARG_COUNT</literal> マクロでした。 </para> <para> 引数の数が正しいかどうかを調べるコードは次のようになります。 <programlisting> if(ZEND_NUM_ARGS() != 2) WRONG_PARAM_COUNT; </programlisting> 関数コール時の引数の数が 2 つでなかった場合、 これはエラーメッセージを表示して終了します。 上のコードは、<literal>WRONG_PARAM_COUNT</literal> マクロの使用例でもあります。 これは、以下のような標準的なエラーメッセージを生成するために使用するものです。 <![CDATA[ "Warning: Wrong parameter count for firstmodule() in /home/www/htdocs/firstmod.php on line 5" ]]> </para> <para> このマクロはデフォルトのエラーメッセージを表示し、呼び出し元に制御を戻します。 このマクロの定義もまた <filename>zend_API.h</filename> にあります。このような内容です。 <programlisting> ZEND_API void wrong_param_count(void); #define WRONG_PARAM_COUNT { wrong_param_count(); return; } </programlisting> ご覧の通り、このマクロは <function>wrong_param_count</function> という名前の内部関数をコールしています。 この関数が警告を表示しています。独自のエラーメッセージを作成するための方法については、 後半の節「情報の表示」を参照ください。 </para> </sect2> <sect2 id="zend.arguments.retrieval"> <title>引数の取得</title> <note> <title> パラメータのパース用の新しい API </title> <para> この章では、Andrei Zmievski による新しい Zend パラメータパース用 API を説明します。この API は PHP 4.0.6 から PHP 4.1.0 の間の開発中に導入されました。 </para> </note> <para> パラメータのパースはあまりにもありふれた操作であり、少し退屈に感じることもあるでしょう。 また、エラーチェックやエラーメッセージは標準化されていたほうがいいでしょう。 PHP 4.1.0 以降では、パラメータのパース用の新しい API を使用することでこれが実現できます。 この API はパラメータの受け取りを劇的に単純化していますが、 可変引数を受け取る関数には使用できないという弱点があります。 しかし、大半の関数では、引数の数は固定です。そのため、 新しい標準として、このパース用 API の使用を推奨します。 </para> <para> パラメータのパース用関数のプロトタイプは、このようになります。 <programlisting> int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...); </programlisting> 最初の引数に、あなたの関数が受け取るパラメータの数を指定します。 ここでは <literal>ZEND_NUM_ARGS()</literal> が使用できます。 2 番目のパラメータは、常に <literal>TSRMLS_CC</literal> マクロでなければなりません。3 番目の引数は、 あなたの関数が受け取る引数の数および型を表す文字列です。 これは、printf の書式指定文字列によって出力内容を指定するのに似ています。 そして最後に、パラメータの値を受け取る変数へのポインタを指定します。 </para> <para> 常に希望通りの型でデータを受け取ることができるよう、 <function>zend_parse_parameters</function> は可能な範囲で型変換を行います。 あらゆるスカラー型は別のスカラー方に変換することが可能です。 しかし、複雑な型 (配列、オブジェクトあるいはリソース) とスカラー型の間の型変換はできません。 </para> <para> パラメータの取得に成功し、かつ型変換でエラーが発生しなかった場合は この関数は <literal>SUCCESS</literal> を返します。それ以外の場合は <literal>FAILURE</literal> を返します。また、 「パラメータの数が一致しない」「型変換ができなかった」 などの情報を含むエラーメッセージを出力します。 </para> <para> 出力されるエラーメッセージは、例えば次のようなものになります。 <screen> Warning - ini_get_all() requires at most 1 parameter, 2 given Warning - wddx_deserialize() expects parameter 1 to be string, array given </screen> もちろん、これらのメッセージにはエラーの発生したファイル名や行番号も含まれています。 </para> <para> 型を指定する文字の一覧をここにまとめます。 <itemizedlist> <listitem> <para><literal>l - </literal>long</para> </listitem> <listitem> <para><literal>d - </literal>double</para> </listitem> <listitem> <para><literal>s - </literal>string (null バイトの可能性もあり) およびその長さ</para> </listitem> <listitem> <para><literal>b - </literal>boolean</para> </listitem> <listitem> <para><literal>r - </literal><literal>zval*</literal> に保存されたリソース</para> </listitem> <listitem> <para><literal>a - </literal><literal>zval*</literal> に保存された配列</para> </listitem> <listitem> <para><literal>o - </literal><literal>zval*</literal> に保存された (あらゆるクラスの) オブジェクト</para> </listitem> <listitem> <para><literal>O - </literal><literal>zval*</literal> に保存された (クラスエントリで指定されているクラスの) オブジェクト</para> </listitem> <listitem> <para><literal>z - </literal><literal>zval*</literal> 自体</para> </listitem> </itemizedlist> 以下の文字は、型指定文字列の中で特別な意味を持ちます。 <itemizedlist> <listitem> <para> <literal>| - </literal>残りのパラメータがオプションであることを表します。 これらのパラメータに対応する保存用変数は、 拡張モジュール自身によってデフォルト値で初期化されなければなりません。 なぜなら、パラメータが渡されていなければパース関数を通過しないからです。 </para> </listitem> <listitem> <para> <literal>/ - </literal>パラメータの後にこの文字を続けると、 そのパラメータに対して <function>SEPARATE_ZVAL_IF_NOT_REF</function> をコールします。これにより、そのパラメータが参照でなければパラメータのコピーが作成されます。 </para> </listitem> <listitem> <para> <literal>! - </literal>パラメータの後にこの文字を続けると、 そのパラメータは指定した型あるいは <literal>NULL</literal> となります (a、o、O、r および z についてのみ適用可能)。 <literal>NULL</literal> 値が渡された場合は、 保存ポインタの値が <literal>NULL</literal> に設定されます。 </para> </listitem> </itemizedlist> </para> <para> この関数の使用法について説明するには、 実際の例を見ていただくのがいちばんでしょう。 <programlisting> <![CDATA[ /* long、文字列とその長さ、そして zval を受け取ります。*/ long l; char *s; int s_len; zval *param; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz", &l, &s, &s_len, &param) == FAILURE) { return; } /* my_ce で指定するクラスのオブジェクト、そしてオプションで double 値を受け取ります。*/ zval *obj; double d = 0.5; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d", &obj, my_ce, &d) == FAILURE) { return; } /* オブジェクト (あるいは null)、そして配列を受け取ります。 オブジェクトに null が渡された場合、obj は NULL となります。*/ zval *obj; zval *arr; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &obj, &arr) == FAILURE) { return; } /* 配列のコピーを受け取ります。*/ zval *arr; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &arr) == FAILURE) { return; } /* 最初の 3 つのパラメータのみを受け取ります (可変引数の関数の場合に有用です)。*/ zval *z; zend_bool b; zval *r; if (zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE) { return; } ]]> </programlisting> </para> <para> 最後の例で、<function>ZEND_NUM_ARGS</function> を使用せずにパラメータ数を 3 としていることに注目しましょう。 こうすることで、可変引数の関数に対して最低限必要な引数の数を指定することができます。 もちろん、もし残りのパラメータについても処理したいのなら <function>zend_get_parameters_array_ex</function> を使用してそれを取得しなければなりません。 </para> <para> 拡張版のパース関数も存在します。 これは、追加のフラグを引数に指定することでその動きを制御します。 <programlisting> int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...); </programlisting> </para> <para> 現在は、渡すことのできるフラグは <literal>ZEND_PARSE_PARAMS_QUIET</literal> だけです。これを指定すると、処理中に発生したエラーメッセージを出力しないようになります。 これは、その関数がさまざまな形式の引数を受け取ることを想定しており、 独自のエラーメッセージで対応したい場合などに有用です。 </para> <para> 例えば、3 つの long 値あるいは 3 つの文字列を受け取る関数は、 このようになります。 <programlisting> <![CDATA[ long l1, l2, l3; char *s; if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC, "lll", &l1, &l2, &l3) == SUCCESS) { /* long の場合 */ } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "s", &s, &s_len) == SUCCESS) { /* 文字列の場合 */ } else { php_error(E_WARNING, "%s() takes either three long values or a string as argument", get_active_function_name(TSRMLS_C)); return; }]]> </programlisting> </para> <para> 上で説明したいずれの場合についても、パラメータの取得処理は慎重に行いましょう。 これ以外の例については、PHP に同梱されている拡張モジュールのソースを 参考にしてください。便利な使用法がいろいろ発見できるでしょう。 </para> </sect2> <sect2 id="zend.arguments.deprecated-retrieval"> <title>引数の取得の古い方法 (廃止予定)</title> <note> <title> 廃止予定のパラメータパース用 API </title> <para> この API は非推奨です。現在は新しい ZEND パラメータパース API が使用されています。 </para> </note> <para> 引数の数をチェックし終えたら、次は引数そのものにアクセスしなければなりません。 そのためには <function>zend_get_parameters_ex</function> の助けを借りることになります。 <programlisting> <![CDATA[ zval **parameter; if(zend_get_parameters_ex(1, &parameter) != SUCCESS) WRONG_PARAM_COUNT; ]]> </programlisting> すべての引数は <envar>zval</envar> コンテナに格納され、 <emphasis>二重に</emphasis>ポイントされる必要があります。 上のコードは、引数を取得してそれをポインタ <envar>parameter</envar> でアクセスできるようにしています。 </para> <para> <function>zend_get_parameters_ex</function> は、少なくとも 2 つの引数を受け付けます。 最初の引数は、取得する引数の数です (これは、 関数がコールされた際の引数の数と同じでなければなりません。 そのため、呼び出し構文をきちんとチェックすることが大切になります)。 2 番目 (およびそれ以降) の引数は、<envar>zval</envar> へのポインタへのポインタへのポインタ (なんてややこしいことでしょう!) です。 これが必要になるのは、私たちが作成した関数内のローカル <envar>**zval</envar> を管理するために Zend は内部で <envar>**zval</envar> を使用しており、 <function>zend_get_parameters_ex</function> はそれに対するポインタを必要とするからです。 </para> <para> <function>zend_get_parameters_ex</function> の返り値は <literal>SUCCESS</literal> あるいは <literal>FAILURE</literal> で、それぞれ (当然のごとく) 成功したこと、あるいは引数の処理に失敗したことを示します。 もっともありがちな失敗の原因は、パラメータの数を間違えることです。 この場合は、 <literal>WRONG_PARAM_COUNT</literal> で関数を抜けなければなりません。 </para> <para> 複数の引数を受け取るには、このようにします。 <programlisting> <![CDATA[ zval **param1, **param2, **param3, **param4; if(zend_get_parameters_ex(4, &param1, &param2, &param3, &param4) != SUCCESS) WRONG_PARAM_COUNT; ]]> </programlisting> </para> <para> <function>zend_get_parameters_ex</function> がエラーとなるのは、 実際の数より多くのパラメータを取得しようとした場合のみです。 もし実際の関数が 5 つの引数でコールされたのに <function>zend_get_parameters_ex</function> では 3 つしか取得しなかった場合、 何もエラーは発生せず、最初の 3 つのパラメータが取得されます。 続けて <function>zend_get_parameters_ex</function> をコールしたとしても、 残りの引数が取得できるわけではなく最初と同じものが得られるだけです。 </para> </sect2> <sect2 id="zend.arguments.variable"> <title>可変引数 / オプションパラメータの扱い</title> <para> もしあなたの関数が可変引数を受け付けるのなら、 さきほどの例が次善の策となることもあるでしょう。ただ、 取りうる可能性のあるすべての引数の数に対して、それぞれ <function>zend_get_parameters_ex</function> コールしなければならず、 不満が残ります。 </para> <para> このような場合には、 <function>zend_get_parameters_array_ex</function> 関数を使うことができます。 これは、引数の数を指定してデータを取得し、それを配列に格納します。 <programlisting> <![CDATA[ zval **parameter_array[4]; /* 引数の数を取得します */ argument_count = ZEND_NUM_ARGS(); /* 引数の数の範囲 (最低 2 個、最大 4 個) */ /* を満たしているかどうかを調べます */ if(argument_count < 2 || argument_count > 4) WRONG_PARAM_COUNT; /* 引数の数が正しかったので、その内容を取得します */ if(zend_get_parameters_array_ex(argument_count, parameter_array) != SUCCESS) WRONG_PARAM_COUNT; ]]> </programlisting> まず、引数の数を調べてそれが予期する範囲内にあることを確かめます。 それから <function>zend_get_parameters_array_ex</function> を使用し、 引数の値へのポインタを <envar>parameter_array</envar> に格納します。 </para> <para> これを非常にうまく実装したのが、PHP の <function>fsockopen</function> を処理するコードです。このコードは <filename>ext/standard/fsock.c</filename> にあり、 <xref linkend='example.fsockopen'/> で見ることができます。 このソースの中に知らない関数が含まれていたとしても、現時点では問題ありません。 すぐにわかるようになります。 </para> <example id='example.fsockopen'> <title>fsockopen() における、PHP の可変引数処理の実装</title> <programlisting> <![CDATA[ pval **args[5]; int *sock=emalloc(sizeof(int)); int *sockp; int arg_count=ARG_COUNT(ht); int socketd = -1; unsigned char udp = 0; struct timeval timeout = { 60, 0 }; unsigned short portno; unsigned long conv; char *key = NULL; FLS_FETCH(); if (arg_count > 5 || arg_count < 2 || zend_get_parameters_array_ex(arg_count,args)==FAILURE) { CLOSE_SOCK(1); WRONG_PARAM_COUNT; } switch(arg_count) { case 5: convert_to_double_ex(args[4]); conv = (unsigned long) (Z_DVAL_PP(args[4]) * 1000000.0); timeout.tv_sec = conv / 1000000; timeout.tv_usec = conv % 1000000; /* fall-through */ case 4: if (!PZVAL_IS_REF(*args[3])) { php_error(E_WARNING,"error string argument to fsockopen not passed by reference"); } pval_copy_constructor(*args[3]); ZVAL_EMPTY_STRING(*args[3]); /* fall-through */ case 3: if (!PZVAL_IS_REF(*args[2])) { php_error(E_WARNING,"error argument to fsockopen not passed by reference"); return; } ZVAL_LONG(*args[2], 0); break; } convert_to_string_ex(args[0]); convert_to_long_ex(args[1]); portno = (unsigned short) Z_LVAL_P(args[1]); key = emalloc(Z_STRLEN_P(args[0]) + 10); ]]> </programlisting> </example> <para> <function>fsockopen</function> が受け付ける引数の数は、 2、3、4、あるいは 5 です。お決まりの変数宣言の後に、 この関数は引数の数が範囲内にあるかどうかを調べます。 それから、<literal>switch()</literal> 文の下に流れていく性質を利用して、 すべての引数を処理します。<literal>switch()</literal> 文は、 まず引数の数が最大 (5 個) であった場合の処理から始まります。 その後、引数の数が 4 個であった場合の処理、3 個であった場合の処理、 と順にたどっていきます。これは、キーワード <literal>break</literal> の記述を省略しているからです。最後の処理を実行した後で <literal>switch()</literal> 文は終了し、 関数の引数が 2 個だけであった場合でも、必要最小限の処理が実行されます。 </para> <para> このように複数ステージの処理を段階的に実行するようにすると、 可変引数の処理がやりやすくなります。 </para> </sect2> <sect2 id="zend.arguments.access"> <title>引数へのアクセス</title> <para> 引数にアクセスするには、すべての引数の型がきちんと定義されていなければなりません。 何度も言いますが、PHP は究極の動的言語なので、時に問題が起こることがあります。 PHP は一切の型チェックを行わないので、 どんな型のデータでも関数に渡すことができてしまいます。 本当は整数値を期待しているのに配列が渡されるかもしれないし、 その逆だってありえます。PHP は、こんな場合でも一切なにも通知しません。 </para> <para> これを防ぐには、これらの API を使用して引数の方を強制的に変換しなければなりません (<xref linkend='tab.arg-conv'/> を参照ください)。 </para> <para> <emphasis>注意:</emphasis> すべての変換関数のパラメータは <envar>**zval</envar> です。 </para> <table id='tab.arg-conv'> <title>引数の変換関数</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.02*"/> <colspec colnum="2" colname="col2" colwidth="1.00*"/> <tbody> <row> <entry colname="col1">関数</entry> <entry colname="col2">説明</entry> </row> <row> <entry colname="col1"><function>convert_to_boolean_ex</function></entry> <entry colname="col2"> Boolean 型への強制的な変換を行います。 Boolean 値が渡された場合は何もしません。 Long、double および <literal>0</literal> を含む文字列、 そして NULL 値は Boolean <literal>0</literal> (FALSE) となります。配列やオブジェクトは、 その元になっているエントリやプロパティの数を基準にして変換されます。 空の配列や空のオブジェクトは FALSE、それ以外は TRUE となります。 その他の値は、すべて Boolean <literal>1</literal> (TRUE) になります。 </entry> </row> <row> <entry colname="col1"><function>convert_to_long_ex</function></entry> <entry colname="col2"> long 型 (デフォルトの整数型) への強制的な変換を行います。 NULL 値、Boolean、リソースおよび long はそのまま何もしません。 double は切り詰められます。整数値を含む文字列は対応する数値表現に変換され、 それ以外の文字列は <literal>0</literal> になります。 配列やオブジェクトは、中身が空の場合に <literal>0</literal>、 それ以外の場合に <literal>1</literal> となります。 </entry> </row> <row> <entry colname="col1"><function>convert_to_double_ex</function></entry> <entry colname="col2"> double 型 (デフォルトの浮動小数点数値型) への強制的な変換を行います。 NULL 値、Boolean、リソース、long、そしてもちろん double はそのまま何もしません。数値を含む文字列は対応する数値表現に変換され、 それ以外の文字列は <literal>0.0</literal> になります。 配列やオブジェクトは、中身が空の場合に <literal>0.0</literal>、 それ以外の場合に <literal>1.0</literal> となります。 </entry> </row> <row> <entry colname="col1"><function>convert_to_string_ex</function></entry> <entry colname="col2"> 文字列への強制的な変換を行います。文字列が渡された場合は何もしません。 NULL 値は空の文字列に変換されます。Boolean TRUE は <literal>"1"</literal>、それ以外の Boolean は空の文字列となります。 long および double はそれぞれ対応する文字列表現に変換されます。 配列は <literal>"Array"</literal>、オブジェクトは <literal>"Object"</literal> という文字列に変換されます。 </entry> </row> <row> <entry colname="col1"><literal>convert_to_array_ex(value)</literal></entry> <entry colname="col2"> 配列への強制的な変換を行います。配列が渡された場合は何もしません。 オブジェクトは、すべてのプロパティが配列に変換されます。 プロパティ名が配列のキー、プロパティの内容が配列の値となります。 NULL 値は空の配列に変換されます。それ以外のすべての値は、 キー <literal>0</literal> に対応する値として元の値を格納した配列となります。 </entry> </row> <row> <entry colname="col1"><literal>convert_to_object_ex(value)</literal></entry> <entry colname="col2"> オブジェクトへの強制的な変換を行います。オブジェクトが渡された場合は何もしません。 NULL 値は空のオブジェクトに変換されます。配列は、そのキーをプロパティに、 その値をプロパティの内容として保持するオブジェクトに変換されます。 その他の型は、すべてプロパティ <literal>scalar</literal> をもつオブジェクトに変換されます。このプロパティの内容は、 変換前の値となります。 </entry> </row> <row> <entry colname="col1"><literal>convert_to_null_ex(value)</literal></entry> <entry colname="col2">NULL 値、つまり空白になるように変換します。</entry> </row> </tbody> </tgroup> </table> <note> <para> これらの振る舞いのデモが、付録 CD-ROM の <filename>cross_conversion.php</filename> で見られます。その出力を <xref linkend='fig.cross-convert'/> に示します。 </para> </note> <figure id='fig.cross-convert'> <title>PHP の型変換の挙動</title> <graphic fileref="figures/zend.04-cross-converter.png"/> </figure> <para> 引数に対してこれらの関数を使用することで、 渡されたデータの型の安全性を確保できます。 渡された型が要求と異なった場合、PHP は空の値 (空の文字列、配列、オブジェクトや 数値の <literal>0</literal>、Boolean の <literal>FALSE</literal> など) を結果として返します。 </para> <para> これは、先ほど説明したサンプルモジュールのコードの一部を引用したものです。 ここで実際に変換関数を使用しています。 <programlisting> <![CDATA[ zval **parameter; if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &parameter) != SUCCESS)) { WRONG_PARAM_COUNT; } convert_to_long_ex(parameter); RETURN_LONG(Z_LVAL_P(parameter)); ]]> </programlisting> パラメータへのポインタを取得した後に、パラメータの値が long 型 (整数値) に変換されます。そしてそれがこの関数の返り値となります。 この値の中身にアクセスするには、<envar>zval</envar> 型についての知識が必要です。その定義を <xref linkend='example.zval-typedef'/> に示します。 </para> <example id='example.zval-typedef'> <title>PHP/Zend <envar>zval</envar> 型定義</title> <programlisting> <![CDATA[ typedef pval zval; typedef struct _zval_struct zval; typedef union _zvalue_value { long lval; /* long 値 */ double dval; /* double 値 */ struct { char *val; int len; } str; HashTable *ht; /* ハッシュテーブル値 */ struct { zend_class_entry *ce; HashTable *properties; } obj; } zvalue_value; struct _zval_struct { /* 変数の情報 */ zvalue_value value; /* 値 */ unsigned char type; /* アクティブな型 */ unsigned char is_ref; short refcount; }; ]]> </programlisting> </example> <para> 実際のところは <envar>pval</envar> (<filename>php.h</filename> で定義) は単なる <envar>zval</envar> (<filename>zend.h</filename> で定義) のエイリアスであり、これは <envar>_zval_struct</envar> をさしています。 そこで、この構造体に注目してみましょう。 <envar>_zval_struct</envar> は「マスタ」構造体であり、 その中には値情報、型情報、参照情報が含まれています。 中に含まれている <envar>zvalue_value</envar> は共用体であり、 変数の値がそこに含まれます。変数の型に応じて、共用体の中の適切なメンバーにアクセスする必要があります。 それぞれの構造体については <xref linkend='tab.struct-zval'/>、 <xref linkend='tab.struct-zvalue-value'/> および <xref linkend='tab.ztype-constants'/> を参照ください。 </para> <table id='tab.struct-zval'> <title>Zend <envar>zval</envar> 構造体</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.66*"/> <tbody> <row> <entry colname="col1">項目</entry> <entry colname="col2">説明</entry> </row> <row> <entry colname="col1"><envar>value</envar></entry> <entry colname="col2"> この変数の内容を含む共用体。詳細は <xref linkend='tab.struct-zvalue-value'/> を参照ください。 </entry> </row> <row> <entry colname="col1"><envar>type</envar></entry> <entry colname="col2"> 変数の型を含みます。使用可能な型については <xref linkend='tab.ztype-constants'/> を参照ください。 </entry> </row> <row> <entry colname="col1"><envar>is_ref</envar></entry> <entry colname="col2"> この変数が参照ではない場合に 0、 他の変数への参照である場合に 1 となります。 </entry> </row> <row> <entry colname="col1"><envar>refcount</envar></entry> <entry colname="col2"> この変数に対する参照の数。この変数に格納されている値への新しい参照が作成されるたびに、 カウンタが 1 増加します。参照が解除されるたびに、カウンタが 1 減少します。 参照カウンタが 0 になった段階で、この値はどこからも参照されていないことになります。 この時点で、自動的にメモリが解放されます。 </entry> </row> </tbody> </tgroup> </table> <table id='tab.struct-zvalue-value'> <title>Zend <envar>zvalue_value</envar> 構造体</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.66*"/> <tbody> <row> <entry colname="col1">項目</entry> <entry colname="col2">説明</entry> </row> <row> <entry colname="col1"><envar>lval</envar></entry> <entry colname="col2"> 変数の型が <literal>IS_LONG</literal>、 <literal>IS_BOOLEAN</literal> あるいは <literal>IS_RESOURCE</literal> である場合にこのプロパティを使用します。 </entry> </row> <row> <entry colname="col1"><envar>dval</envar></entry> <entry colname="col2"> 変数の型が <literal>IS_DOUBLE</literal> である場合にこのプロパティを使用します。 </entry> </row> <row> <entry colname="col1"><envar>str</envar></entry> <entry colname="col2"> 型が <literal>IS_STRING</literal> の変数にアクセスする際に、この構造体を使用します。 <envar>len</envar> には文字列の長さが含まれ、 <envar>val</envar> が文字列へのポインタとなります。Zend は C の文字列を使用しているので、 文字列の長さには、最後の <literal>0x00</literal> のぶんも含まれます。 </entry> </row> <row> <entry colname="col1"><envar>ht</envar></entry> <entry colname="col2"> 変数が配列である場合に、この項目は配列のハッシュテーブルエントリへのポインタとなります。 </entry> </row> <row> <entry colname="col1"><envar>obj</envar></entry> <entry colname="col2"> 変数の型が <literal>IS_OBJECT</literal> である場合にこのプロパティを使用します。 </entry> </row> </tbody> </tgroup> </table> <table id='tab.ztype-constants'> <title>Zend 変数の型を表す定数</title> <tgroup cols="2"> <colspec colnum="1" colname="col1" colwidth="1.00*"/> <colspec colnum="2" colname="col2" colwidth="1.65*"/> <tbody> <row> <entry colname="col1">定数</entry> <entry colname="col2">説明</entry> </row> <row> <entry colname="col1"><literal>IS_NULL</literal></entry> <entry colname="col2">NULL (空白) 値を表します。</entry> </row> <row> <entry colname="col1"><literal>IS_LONG</literal></entry> <entry colname="col2">long (整数) 値。</entry> </row> <row> <entry colname="col1"><literal>IS_DOUBLE</literal></entry> <entry colname="col2">double (浮動小数点) 値。</entry> </row> <row> <entry colname="col1"><literal>IS_STRING</literal></entry> <entry colname="col2">文字列。</entry> </row> <row> <entry colname="col1"><literal>IS_ARRAY</literal></entry> <entry colname="col2">配列を表します。</entry> </row> <row> <entry colname="col1"><literal>IS_OBJECT</literal></entry> <entry colname="col2">オブジェクト。</entry> </row> <row> <entry colname="col1"><literal>IS_BOOL</literal></entry> <entry colname="col2">Boolean 値。</entry> </row> <row> <entry colname="col1"><literal>IS_RESOURCE</literal></entry> <entry colname="col2"> リソース (リソースについては、 以下の適切なセクションを参照ください)。 </entry> </row> <row> <entry colname="col1"><literal>IS_CONSTANT</literal></entry> <entry colname="col2">定数 (定義済み) 値。</entry> </row> </tbody> </tgroup> </table> <para> long 値にアクセスするには <envar>zval.value.lval</envar>、 double 値にアクセスするには <envar>zval.value.dval</envar>、といったように使用します。 すべての値は共用体に保存されるので、不適切なメンバーにアクセスすると、 無意味な結果を得ることになります。 </para> <para> 配列やオブジェクトへのアクセスは少し複雑なので、後で説明します。 </para> </sect2> <sect2 id="zend.arguments.by-reference"> <title>参照渡しされた引数の扱い</title> <para> 参照渡しの引数を受け取って関数内部でそれを変更しようとする場合は、 少々注意が必要です。 </para> <para> 敢えて説明しませんでしたが、ここで示している状況では、 関数のパラメータとして受け取った <envar>zval</envar> に対する書き込み権限はありません。 もちろん関数内で独自に作成した <envar>zval</envar> を変更することは可能ですが、 Zend の内部データを参照している <envar>zval</envar> は、 決して変更してはいけません。 </para> <para> これまで説明してきたのは、いわゆる <function>*_ex</function> 系の API ばかりです。お気づきかもしれませんが、これまで使用してきた API 関数は <function>zend_get_parameters</function> ではなくて <function>zend_get_parameters_ex</function> でしたし、また <function>convert_to_long</function> ではなくて <function>convert_to_long_ex</function> でした。これらの <function>*_ex</function> 系の関数は、いわゆる「拡張」Zend API と呼ばれるものです。 これらは、以前の API に比べて速度が少し向上しているのですが、 それと引き換えに読み込み専用のアクセスしかできないようになっています。 </para> <para> Zend は内部的には参照を使用しているので、 さまざまな変数が同じ値を参照することもありえます。 <envar>zval</envar> コンテナへの書き込みアクセスをするためには、 このコンテナが保持する値が他と完全に分離していること、 つまり他のコンテナから参照されていないことが必要です。 <envar>zval</envar> コンテナが他のコンテナから参照されている場合に その <envar>zval</envar> を変更すると、この <envar>zval</envar> を参照しているその他のコンテナの内容も変わってしまいます (それらも変更後の値を指すようになるからです)。 </para> <para> <function>zend_get_parameters_ex</function> は、単に <envar>zval</envar> コンテナへのポインタを返します。そこに参照が含まれているかどうかは考慮しません。 一方、これに対応する伝統的な API である <function>zend_get_parameters</function> は、参照をチェックします。 参照が見つかった場合には、独立した <envar>zval</envar> コンテナを新しく作成し、参照先のデータをそこにコピーし、 その新しく作成した (他とは分離している) コンテナへのポインタを返します。 </para> <para> この操作のことを <emphasis>zval separation (zval の分離)</emphasis> (あるいは pval separation) と言います。<function>*_ex</function> API は zval の分離を行わないません。そのために大幅に高速化されましたが、 その代償として書き込みアクセスができなくなっています。 </para> <para> とは言うものの、パラメータを変更するには書き込みアクセスをしなければなりません。 このような場合のために、Zend には特別な方法が用意されています。 関数のパラメータが参照渡しされた場合は、自動的に zval の分離が行われるのです。 つまり、PHP で下のように関数をコールすると、<envar>$parameter</envar> が独立した値として渡されることを Zend が自動的に保証してくれるのです。 これにより、書き込みが可能となります。 <programlisting> my_function(&amp;$parameter); </programlisting> </para> <para> しかし、これは値渡しのパラメータには適用<emphasis>されません</emphasis>! 参照渡し以外で渡されたパラメータ以外は、読み込み専用となります。 </para> <para> これらの性質により、パラメータを扱う際にはそれが参照なのかそうでないのかをしっかり見極める必要があります。 さもないと、思ってもいない結果を引き起こすことになります。 パラメータが参照渡しされたかどうかを調べるためには、マクロ <literal>PZVAL_IS_REF</literal> を使用します。このマクロは <literal>zval*</literal> を受け取り、それが参照かそうでないかを返します。 <xref linkend='example.pass-by-ref'/> に実際の使用例があります。 </para> <example id='example.pass-by-ref'> <title>パラメータが参照で渡されたかどうかを調べる</title> <programlisting> <![CDATA[ zval *parameter; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &parameter) == FAILURE) return; /* パラメータが参照で渡されたかどうかを調べます */ if (!PZVAL_IS_REF(parameter)) { { zend_error(E_WARNING, "パラメータは参照渡しされませんでした"); RETURN_NULL(); } /* パラメータを変更します */ ZVAL_LONG(parameter, 10); ]]> </programlisting> <graphic fileref="figures/zend.05-reference-test.png"/> </example> </sect2> <sect2 id="zend.arguments.write-safety"> <title>Assuring Write Safety for Other Parameters</title> <para> <function>zend_get_parameters_ex</function> で取得したパラメータのうち、 参照渡しではないものについても値を変更したくなる場合があるかもしれません。 そんなときには、マクロ <literal>SEPARATE_ZVAL</literal> を使用します。 これは、指定したコンテナについて zval の分離を行います。 新しく作成された <envar>zval</envar> は内部のデータとは分離されており、 ローカルスコープでしか使用できません。つまり、 スクリプト全体のコンテキストに影響を与えることなく データを変更したり破壊したりできるようになるのです。 <programlisting> <![CDATA[ zval **parameter; /* パラメータを取得します */ zend_get_parameters_ex(1, &parameter); /* この時点では、<parameter> はまだ */ /* Zend の内部データバッファと紐付いています */ /* <parameter> を書き込み可能にします */ SEPARATE_ZVAL(parameter); /* この時点で、<parameter> が変更できるようになります。*/ /* グローバルに影響を与えることはありません */ ]]> </programlisting> <literal>SEPARATE_ZVAL</literal> は、<function>emalloc</function> を使用して新しい <envar>zval</envar> コンテナを確保します。 つまり、このメモリの開放を忘れてしまったとしても、 スクリプトの終了時に自動的に破棄されるということです。 しかし、コンテナを開放せずにこのマクロをコールし続けると、 RAM が散らかってしまいます。 </para> <para> <emphasis>注意:</emphasis> 書き込み権限の問題については、 「伝統的な」API (<function>zend_get_parameters</function> やその他) を使用すれば簡単に回避できます。しかし、この API は非推奨のようなので、今後この章では深入りしません。 </para> </sect2> </sect1> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->