変数の作成

- 変数の作成 + 変数の処理

- Introduction to Variables + 変数入門 - A good understanding of how variables are stored and manipulated is essential to becoming a Hacker. - The engine attempts to cover up the complexity of the concept of a variable that can be any type by - providing a uniform and intuitive set of macros for accessing the structures various fields. As the Hacker works - through this chapter, they should become comfortable with the terminology and concepts involved with Variables in PHP. + 変数がどのように格納され処理されているのかについてきちんと理解することは、 + ハッカーになるための第一歩です。エンジンは、構造体のさまざまな + フィールドにアクセスするための統一された直感的なマクロを提供することで、 + それがどのような型の変数であっても、その概念の複雑さを隠蔽しようとします。 + この章の中身に沿って学習していけば、ハッカーはPHPの変数に関する + 専門用語やその概念についての理解を深めることができるはずです。 - PHP is a dynamic, loosely typed language, that uses copy-on-write and reference counting. + PHPはコピーオンライトや参照カウント法を使う、動的で型の制約がゆるい言語です。 + - To clarify what exactly is meant by the statement above: PHP is a high level language, weak typing is implicit of the engines preference to - convert, or coerce variables into the required type at execution time. Reference counting is the means by which the engine can deduce when a - variable no longer has any references in the users code, and so is able to free the structures associated with the variable. + 前述の内容もう少し正確に言うと、PHPは高水準言語であり、緩い型付けにより変数は + エンジニアの好みに応じて暗黙に解釈され、実行時に必要な型に強制的に変換されます。 + 参照カウント法は、ある変数がユーザーのコードの中でもはや参照されなくなったことを + エンジンが推測し、その変数に関連付けられた構造体を開放するという仕組みです。 - All variables in PHP are represented by one structure, the zval: + PHP内部の変数は、すべてzvalと呼ばれるひとつの構造体で表現されています。 - The zval_value is a union which can represent all types a variable may hold: + zval_valueは、ひとつの変数が持ちうるすべての型を表現可能な共用体です。 - It should be clear from the structures above that a variable can be of one type, the variable data is represented by the appropriate field in the zval_value union. The zval itself holds the type, reference count and a flag to indicate if a variable is a reference. + この構造体により、ある変数はいずれかひとつの型を持つことができ、そのデータは + zval_value共用体の中の適切なフィールドによって表現されている + ことがわかります。zval自体に型や参照回数と、その変数がまだ参照 + されているかどうかを示すフラグを持っています。 - Native Type Constants + ネイティブ型定数 - Constant - Mapping + 定数 + マッピング IS_NULL - no value is set in this case + 値がセットされていない @@ -106,28 +114,29 @@

- There are additional constants that help to identify internal types such as constant arrays and callable objects, their usage is outside the scope of this part of the documentation. + 上記の他にも、定数の配列や callable オブジェクトといった内部的な型を + あらわす定数があるのですが、それらの利用法についてはこのドキュメントでは扱いません。 - - The following table defines the macros exposed by the engine for working with zval values: + エンジンが公開しているマクロのうち、zval値で扱えるものを + 以下の表に示します。 - Accessor Macros + アクセサ・マクロ - Prototype - Accesses - Description + プロトタイプ + アクセス + 説明 zend_uchar Z_TYPE(zval zv) type - returns the type of the value + valueの型を返す @@ -139,7 +148,7 @@ zend_bool Z_BVAL(zval zv) value.lval - cast long value to zend_bool + long のvalueを zend_bool にキャスト @@ -151,67 +160,68 @@ long Z_RESVAL(zval zv) value.lval - returns the resource list identifier for value + リソース一覧におけるvalueの識別子を返す char* Z_STRVAL(zval zv) value.str.val - return the string value + 文字列のvalueを返す int Z_STRLEN(zval zv) value.str.len - return the length of the string value + 文字列valueの文字数を返す HashTable* Z_ARRVAL(zval zv) value.ht - return the HashTable (array) value + ハッシュテーブル（配列）のvalueを返す zend_object_value Z_OBJVAL(zval zv) value.obj - returns object value + オブジェクトのvalueを返す uint Z_OBJ_HANDLE(zval zv) value.obj.handle - returns the object handle for object value + オブジェクトvalueのオブジェクトハンドルを返す zend_object_handlers* Z_OBJ_HT_P(zval zv) value.obj.handlers - returns the handler table for object value + オブジェクトvalueのハンドラテーブルを返す zend_class_entry* Z_OBJCE(zval zv) value.obj - returns the class entry for object value + オブジェクトvalueのクラスエントリを返す HashTable* Z_OBJPROP(zval zv) value.obj - returns the properties of object value + オブジェクトvalueのプロパティを返す HashTable* Z_OBJPROP(zval zv) value.obj - returns the properties of object value + オブジェクトvalueのプロパティを返す HashTable* Z_OBJDEBUG(zval zv) value.obj - if an object has the get_debug_info handler set, it is called, else Z_OBJPROP is called + オブジェクトに get_debug_info ハンドラがセットされている + 場合はそれが呼ばれ、そうでなければ Z_OBJPROP が呼ばれる @@ -219,57 +229,58 @@

- Please check the chapter for details how reference counting and references work in detail. + の章をチェックして、 + 参照カウント法や参照がどのような仕組みで動いているのかを調べてみてください。 - Reference Count Manipulation + 参照カウントの操作 - Prototype - Description + プロトタイプ + 説明 zend_uint Z_REFCOUNT(zval zv) - returns the reference count of the value + valueの参照カウントを返す zend_uint Z_SET_REFCOUNT(zval zv) - sets the reference count of the value, returning it + valueの参照カウントをセットしてそれを返す zend_uint Z_ADDREF(zval zv) - pre-increments the reference count of value, returning it + valueの参照カウントを事前インクリメントしてそれを返す zend_uint Z_DELREF(zval zv) - pre-decrements the reference count of value, returning it + valueの参照カウントを事前デクリメントしてそれを返す zend_bool Z_ISREF(zval zv) - tells if the zval is a reference + zval が参照かどうかを返す void Z_UNSET_ISREF(zval zv) - set is_ref__gc to 0 + is_ref__gc を 0 にする void Z_SET_ISREF(zval zv) - set is_ref__gc to 1 + is_ref__gc を 1 にする void Z_SET_ISREF_TO(zval zv, zend_uchar to) - set is_ref__gc to to + is_ref__gc をtoにする @@ -277,83 +288,100 @@

- The Z_* macros above all take a zval, they are all defined again suffixed with _P to take a pointer to a zval, for example zend_uchar Z_TYPE_P(zval* pzv), and again suffixed with _PP to take a pointer to a pointer to a zval, for example zend_uchar Z_TYPE_PP(zval** ppzv) + + 前述の Z_* マクロはどれも１個の zval を受け取りますが、これらに _P サフィックス + がついた、たとえばzend_uchar Z_TYPE_P(zval* pzv)のようなマクロも + 定義されていて、これらはすべて zval へのポインタを受け取ります。さらに、たとえば + zend_uchar Z_TYPE_PP(zval** ppzv)のように _PP サフィックスがついた + ものもあり、これらは zval へのポインタのポインタを受け取ります。 - Creation, Destruction, Separation and Copying + 生成、破壊、分割、コピー - Prototype - Description + プロトタイプ + 説明 ALLOC_ZVAL(zval* pzval) - emallocs pzval + pzvalを emalloc する ALLOC_INIT_ZVAL(zval* pzval) - emallocs pzval, and points pzval at a null typed zval for sanity + pzvalを emalloc し、pzvalは初期化のために + NULL として型付けられた zval を指すようにする MAKE_STD_ZVAL(zval* pzval) - emallocs pzval, setting the refcount to 1 + pzvalを emalloc し、参照カウントを + 1にする ZVAL_COPY_VALUE(zval* dst, zval* src) - sets the value and type of dst from the value and type of src + srcの値と型をdstの値と型としてセットする + INIT_PZVAL_COPY(zval* dst, zval*dst) - performs ZVAL_COPY_VALUE, setting refcount of dst to 1, and setting is_ref__gc to 0 + ZVAL_COPY_VALUE を実行し、dstの参照カウントを 1 にし、 + is_ref__gc を0にする SEPARATE_ZVAL(zval** ppzval) - if the refcount of ppzval is >1, redirects *ppzval to a newly emalloc'd, copied, and constructed zval of the same type and value + ppzvalの参照カウントが 1 より大きい場合、新たに emalloc + して zval の中身をコピーし、zval と同じ型で同じ値にした場所を + *ppzvalが指すようにする SEPARATE_ZVAL_IF_NOT_REF(zval** ppzval) - if *ppzval is not a reference, will perform SEPARATE_ZVAL on ppzval + *ppzvalが参照ではない場合、ppzvalに対して + SEPARATE_ZVAL を行う SEPARATE_ZVAL_TO_MAKE_IS_REF(zval** ppzval) - if *ppzval is not a reference, performs SEPARATE_ZVAL then Z_SET_ISREF_PP on ppzval + *ppzvalが参照ではない場合、ppzvalに対して + SEPARATE_ZVAL と Z_SET_ISREF_PP を行う COPY_PZVAL_TO_ZVAL(zval dst, zval** src) - results in dst being a copy of src without affecting the refcount of src + srcの参照カウントを変更せずに、dstを + srcのコピーにする MAKE_COPY_ZVAL(zval** src, zval* dst) - performs INIT_PZVAL_COPY, then zval_copy_ctor on the new zval + INIT_PZVAL_COPY を行い、新しい zval に対して zval_copy_ctor する + void zval_copy_ctor(zval** pzval) - performs maintenance of reference counts, used widely throughout the engine + 参照カウントをメンテナンスする。エンジン全体を通して広く使われる。 + void zval_ptr_dtor(zval* pzval) - decrements the refcount for the variable, if no refcounts remain the variable is destroyed + 変数の参照カウントをデクリメントする。 + 参照カウントが 0 になったら変数は破壊される。 FREE_ZVAL(zval* pzval) - efrees pzval + pzvalを efree する @@ -361,19 +389,29 @@

- Objects and Resources have a reference count as part of their respective structures, when zval_ptr_dtor is called on either, their appropriate del_ref method is executed. See Working with Objects and Working with Resources for more information. + オブジェクトとリソースは、それぞれの構造体の一部として参照カウントを + 持っています。これらについて zval_ptr_dtor が呼ばれると、それぞれにあった del_ref + が実行されます。詳細はオブジェクトの扱いとリソースの扱いを参照してください。 + - If the Hacker only has room to remember two more functions, they should be zval_copy_ctor and zval_ptr_dtor, these are at the basis of the engines reference counting mechanisms and it is important to note that zval_copy_ctor does not actually result in any copying occuring under normal circumstances, it simply increases the reference count. By the same token, zval_ptr_dtor only really destroys a variable when there are no references remaining to it and the refcount is at 0. + さらにハッカーが知っておくべき機能をふたつだけ挙げるとすれば、 + それはzval_copy_ctorとzval_ptr_dtorでしょう。これらは + エンジンにおける参照カウントメカニズムの基本です。重要なことは、通常の環境で + zval_copy_ctorが呼ばれても、実際には何も起こらないことです。 + これは単に参照カウントを増やしているだけです。同様に、zval_ptr_dtor + が本当に変数を破壊するのは、それを参照するものがなくなって、参照カウントが 0 + になった時だけです。 - PHP is weakly typed, as such the engine provides API functions for converting variables from one type to another. + PHP 自体は弱い型付けしか行いませんが、エンジンが変数の型を別の型にするための + API 関数を提供しています。 - Type Conversion + 型の変換 - Prototype + プロトタイプ @@ -415,37 +453,44 @@

- convert_func_t functions should have the prototype (void) (zval* pzval) + convert_func_t 関数には(void) (zval* pzval) + というプロトタイプが必要です。 - By now you should have a good understanding of: the types that are native to the engine, how to detect types and read zval values, how to manipulate refcounts, and other zval flags + ここまで読んでもらえたので、あなたはネイティブからエンジンまでの型、 + 型の検出とzval 値の読み取り方法、参照カウントや zval のフラグの操作等についての + 理解が進んだはずです。

- Working with Arrays + 配列の扱い - Arrays are stored in HashTable strucures, and have the zval type IS_ARRAY. The API functions for creating, destroying and manipulating these structures as variables are documented here and can be found in Zend/zend_API.h + 配列は HashTable 構造体に格納され、zval の型は IS_ARRAY となります。ここでは、 + これらの構造体を変数として作成したり破壊したり操作したりする API 関数について + 説明します。これらの内容は Zend/zend_API.hでも確認できます。 - HashTable as Variable API + 変数としての HashTable の API - Prototype - Description + プロトタイプ + 説明 void array_init(zval* pzval) - initializes the variable as a HashTable, setting type and appropriate destructor function for the HashTable + 変数をHashTableとして初期化し、そのHashTable + に対して型と適切なデストラクタ関数を設定する void array_init_size(zval* pzval) - initializes the variable as array_init with a minimum of size buckets + 最小限size個の入れ物を用意して変数を array_init で初期化する + @@ -453,15 +498,18 @@

- Do not squint too hard looking for array_destroy: to destroy a variable array you should call zval_ptr_dtor on the variable, if there are no other references to the variable it will result in the array being destroyed. + 何度も array_destroy を呼び出さないようにしてください。変数の配列を破壊 + するには、その変数に対してzval_ptr_dtorをコールします。その変数 + へのその他の参照がなくなった時点で、自動的にその配列の中身も破壊されます。 + - Indexed Arrays API + インデックス配列用の API - Prototype + プロトタイプ @@ -538,11 +586,11 @@

- Associative Arrays API + 連想配列用 API - Prototype + プロトタイプ @@ -619,46 +667,62 @@

- add_*_string functions that accept a parameter named duplicate, will duplicate the string with estrndup when duplicate is true + + duplicate という名前のパラメータを取る add_*_string 関数群は、duplicate + が真の場合、estrndupを使って文字列を複製します。 - add_*_zval functions do not adjust the refcount of the value parameter + add_*_zval 関数はvalueパラメータの参照カウントを調整しません。 + - To perform more advanced operations on array variables we must use the HashTable API directly. + 配列変数に対してさらに高度な操作をしたい場合、直接 HashTable API を使う必要があります。

- Working with HashTable + HashTable の扱い - The HashTable structure serves many purposes in PHP and can be found everywhere, a good understanding of it's functionality is a preqrequisite of being a good Hacker. + PHP の内部で多くの役割を提供するHashTable構造体は至る所で + 使われており、この機能を理解することはよいハッカーになるための + 必要条件です。 - The HashTable implemented by the engine is a standard HashTable, that is to say, a key => value based store, where the keys are always strings, whose hashes are calculated with a built in hashing algorythim zend_inline_hash_func(const char* key, uint length), which results in good distribution, and reasonable usage. + エンジンにおけるHashTableの実装は標準のHashTableです。 + つまりキー => 値をベースにした格納方式であり、キーは常に文字列で、そのハッシュ値は + ビルトインのハッシュアルゴリズム + zend_inline_hash_func(const char* key, uint length)により計算されます。 + これは広く流通しており、妥当な利用法と言えます。 - The internal structure and exact operation of HashTable is out of the scope of this document, this document serves to inform you of the API's available and how best to use them. For a more detailed picture of the HashTable see Zend/zend_hash.h. + HashTableの内部構造や厳密な操作についてはこの文書の範疇を超えます。 + この文書では API の入手や最適な利用法などについてご紹介しています。HashTable + に関する詳細な考え方等はZend/zend_hash.hを参照してください。 - Unless otherwise stated, these functions all return FAILURE if the requested operation fails for any reason, otherwise SUCCESS is returned. + 特に記載のない限り、これらの関数は何らかの原因で要求した操作ができない場合 + FAILUREを返し、そうでなければSUCCESSを返します。 - It is important to remember that ordinarily HashTable API functions expect key lengths to be the length of the null terminated string, including the null termination, in other words they expect strlen(key) + 1 + HashTable API 関数は通常、キーの長さは NULL で終端された文字列の + 長さに等しいことを期待していることに気をつけてください。これには NULL 終端の分も + 含みます。つまり、strlen(key) + 1を期待しているということです。 - Below are some typedefs you should know when interacting with HashTable. They are mostly self explanitory and will allow the Hacker to fully understand the prototypes below properly. + HashTableを使う際に知っておくべき typedef 定義を以下に記載します。 + これらのほとんどは定義そのものが説明のようになっているので、ハッカー + はこれらのプロトタイプを深く理解できるはずです。 @@ -671,7 +735,10 @@ - Initializes the hash table to hold at least size elements, hash exists for historical reasons and is always ignored, zend_inline_hash_func is always used as the hashing function. destructor may be NULL. + ハッシュテーブルを初期化して、少なくともsize個の要素を + 保持する。hashは歴史的な経緯により存在するだけで常に無視される。 + zend_inline_hash_funcが常にハッシュ関数として使われる。 + destructorはNULLでもよい。 @@ -679,7 +746,9 @@ - adds data to the table using the specified key, where the key is length bytes long (and will be copied from key to the table). If the key is set FAILURE will be returned. + 指定されたkeyを使ってテーブルにdataを追加する。 + キーはlengthバイトの長さを持つ（そしてkeyからテーブル + にコピーされる）。キーが存在すると FAILURE が返される。 @@ -687,7 +756,10 @@ - adds data to the table using the specified key, where the key is length bytes long (and will be copied from key to the table). If the key has been set previously the old data has dtor_func_t called on it and the existing data is replaced with data + 指定されたkeyを使ってテーブルにdataを追加する。 + キーはlengthバイトの長さを持つ（そしてkeyからテーブル + にコピーされる）。キーが存在した場合、古いデータに対してdtor_func_t + が呼ばれ、既存のデータはdataで上書きされる。 @@ -695,7 +767,8 @@ - searches the table for key, setting *data and returning SUCCESS if it is found. + テーブルをkeyで検索し、見つかったら*data + をセットして SUCCESS を返す。 @@ -703,7 +776,7 @@ - returns positively if key is found in ht + htにkeyがあれば正の値を返す。 @@ -711,7 +784,7 @@ - removes the entry identified by key from the table if found + テーブル内にkeyで特定されるエントリがあれば削除する。 @@ -719,7 +792,8 @@ - updates the entry at index in ht, with the data at data + htの中のindexで指定されたエントリのデータを + dataで更新する。 @@ -727,7 +801,8 @@ - deletes the entry at index from ht + htからindexで指定されたエントリを削除する。 + @@ -735,7 +810,8 @@ - redirects *data to the data identified by index in ht + htの中でindexで指定されたデータを + *dataにリダイレクトする。 @@ -743,7 +819,7 @@ - returns positively if index is found in ht + htにindexがあれば正の値を返す。 @@ -751,7 +827,7 @@ - returns the index of the next free element in ht + htの中で次に利用可能な要素のインデックスを返す。 @@ -759,68 +835,85 @@ - zend_hash_* functions that accept void* data should normally cast it to (void**) (ie, (void**) &data) + zend_hash_* 関数のうちvoid* dataを受け付けるものは、 + 通常それを(void**) (すなわち(void**) &data)に + キャストしなければいけません。 - Traversing the HashTable is often necessary, to do this you provide a pointer to a HashTable, with an optional HashPosition - a structure internal to the HashTable API that allows traversal not to affect the internal position of HashTable. The following traversal functions are provided, and an example usage found below. + HashTable の中を行き来しなければならない場合も少なくありません。 + これを行うには、HashTableへのポインタに加えてHashPosition + オプションを指定します。これは HashTable API への内部構造であり、HashTable の + 内部位置に影響を与えずに内部を移動できるようになります。以下の移動用関数が提供 + されており、以下にその利用例を示します。 - HashTable Traversal API + HashTable 内の移動 API int zend_hash_internal_pointer_reset(HashTable* ht) - resets the internal pointer of ht to the start + htの内部ポインタを開始位置にリセットする。 int zend_hash_internal_pointer_reset_ex(HashTable* ht, HashPosition position) - sets position the the start of ht + positionをhtの開始位置にセットする。 int zend_hash_get_current_data(HashTable* ht, void* data) - gets the data at the current position in ht, data should be cast to void**, ie: (void**) &data + htの現在位置にあるデータを取得する。data + はvoid**にキャストしなければならない + （すなわち(void**) &data）。 int zend_hash_get_current_data_ex(HashTable* ht, void* data, HashPosition position) - sets data to the data at position in ht + htの中でdataをposition + の位置にセットする。 int zend_hash_get_current_key(HashTable* ht, void* data, char**key, uint klen, ulong index, zend_bool duplicate) - sets key, klen, and index from the key information at the current position. The possible return values HASH_KEY_IS_STRING and HASH_KEY_IS_LONG are indicative of the kind of key found at the current posision. + 現在位置のキーの情報から key, klen, + index を取得する。戻り値として HASH_KEY_IS_STRING や + HASH_KEY_IS_LONG が返される場合があるが、これは現在位置にその種類のキーが + あったことを表している。

int zend_hash_get_current_key_ex(HashTable* ht, void* data, char**key, uint klen, ulong index, zend_bool duplicate, HashPosition position)

- sets key, klen, and index from the key information at position. The possible return values HASH_KEY_IS_STRING and HASH_KEY_IS_LONG are indicative of the kind of key found at position. + position位置のキーの情報から key, + klen, index を取得する。戻り値として + HASH_KEY_IS_STRING や HASH_KEY_IS_LONG が返される場合があるが、 + これは現在位置にその種類のキーがあったことを表している。 int zend_hash_move_forward(HashTable* ht) - moves the internal pointer of ht to the next entry in ht + htの内部ポインタをht内の次のエントリに動かす。 + int zend_hash_move_forward_ex(HashTable* ht, HashPosition position) - moves position to the next entry in ht + positionをht内の次のエントリに動かす。

- The functions above allow traversal over a HashTable to be much like a normal loop, which will look something like: + 前述の関数は、HashTable内部を通常のループのように移動できます。 + たとえば以下のように使います。 - If a HashTable has been passed into the engine, it is a good idea to use the zend_hash_*_ex API to avoid unexpected behaviour in userland. + HashTableをエンジンに渡した場合、意図しない事態にならないように、 + ユーザーランドでは zend_hash_*_ex API を使うとよいでしょう。 - If a duplicate of the key is requested and HAS_KEY_IS_STRING is returned the caller must efree the duplicated key + キーのduplicateを要求してHAS_KEY_IS_STRING + が返された場合、呼び出し元は重複キーをefreeしなければなりません。 + - In addition to traversal, the engine provides API functions for merging, copying, and comparing HashTables. These are all concepts that the Hacker should be familiar with. A concept possibly not in the repertoire of the Hacker is applying, which is lamens terms is functionality of the HashTable API allowing the Hacker to pass a callback function to be executed on every entry in a HashTable. + 内部移動以外にも、エンジンではハッシュテーブルのマージ、コピー、比較といった + API を提供しています。ハッカーはこれらのどの概念にも精通して + いなければなりません。 + 関数の適用 (apply) という概念にはなじみがない人もいるかもしれません。 + 要するにこれは、HashTable API の機能を使ってコールバック関数を渡して、 + HashTable中のすべてのエントリでそれを実行させる仕組みのことです。 - Copying, Merging and Sorting + コピー、マージ、ソート @@ -865,7 +967,9 @@ - Copies the contents of source to target. tmp should be an unallocated temporary pointer of the appropriate type, used during copying. size is the size of each element. + sourceの中身をtargetにコピーする。 + tmpにはコピーの中で使われる領域確保されていない適切な型の + ポインタを、sizeには各要素の個数を指定する。 @@ -873,7 +977,8 @@ - Merges the contents of source into destination, replacing existing entries only where overwrite is true. + sourceの中身をdestinationにマージする。 + overwriteが真の場合、既存のエントリを置き換える。 @@ -881,7 +986,8 @@ - renumber controls if indexes should be preserved, see the typedefs at the start of this section for more information + renumberはインデックスを保持するかどうかを制御する。 + 詳細はこの章の最初に出てきた typedef を参照のこと。 @@ -889,14 +995,17 @@

- When a function accepts a copy_ctor_func_t pCopyConstructor, the function passed with be executed upon creation of every new entry in the HashTable. The most common copy constructor used within the engine is a wrapper around zval_copy_ctor, the macro ZVAL_COPY_CTOR. + ある関数がcopy_ctor_func_t pCopyConstructorを受け付ける場合、 + 一緒に渡された関数はHashTable内で新しいエントリが生成されるたびに + 実行されます。エンジン内で使われる通常のコピーコンストラクタのほとんどは、 + ZVAL_COPY_CTORマクロのzval_copy_ctorのラッパーです。

- Working with Objects + オブジェクトの扱い