diff --git a/reference/ffi/book.xml b/reference/ffi/book.xml new file mode 100644 index 0000000000..d554704f3f --- /dev/null +++ b/reference/ffi/book.xml @@ -0,0 +1,72 @@ + + + + + + + 外部関数インターフェース + FFI + + + &reftitle.intro; + + この拡張は、Zend 拡張 API の深い知識が無くとも、あるいは第三の中間言語を学ぶことをせずとも、 + 純粋な PHP で共有ライブラリ (.DLL または .so) + を読み込んだり、C の関数を呼び出したり、C のデータ構造にアクセスしたりすることを + 可能とします。 + 公開 API は単一のクラス FFI として実装されています。 + このクラスの static メソッド (そのうちのいくつかは非 static メソッドとしても呼び出せます) や + オーバーロードされたオブジェクトメソッドが、実際の C のデータとのやり取りを行います。 + + + + FFI は、システムと低レベルでやり取りできるため危険です。 + FFI 拡張は、C 言語および使用する C API についての実用的な知識を持つ開発者のみが + 用いるべきです。リスクを最小化するため、FFI API の使用は + ffi.enable &php.ini; ディレクティブによって制限できます。 + + + + + FFI 拡張は、古くからある PHP 拡張の API を廃止しようとしているわけではなく、 + C の関数やデータ構造へのアドホックなインターフェースを提供するにすぎません。 + + + + + 今のところ、FFI のデータ構造へのアクセスは、ネイティブな PHP の配列やオブジェクトへのアクセスと比べて + 非常に (約 2 倍) 低速です。したがって、速度のために FFI 拡張を使うことには意味がありません。 + しかし、メモリ消費を減らすために使うのは意味があるかもしれません。 + + + + + &reference.ffi.setup; + &reference.ffi.examples; + &reference.ffi.ffi; + &reference.ffi.ffi.cdata; + &reference.ffi.ffi.ctype; + &reference.ffi.ffi.exception; + &reference.ffi.ffi.parserexception; + + + diff --git a/reference/ffi/configure.xml b/reference/ffi/configure.xml new file mode 100644 index 0000000000..3e4633bf76 --- /dev/null +++ b/reference/ffi/configure.xml @@ -0,0 +1,41 @@ + + + + +
+ &reftitle.install; + + + FFI 拡張を有効にするには、 + を付けて + PHP をビルドする必要があります。 + + + + Windows ユーザーが FFI 拡張を有効にするには、 + &php.ini; に php_ffi.dll を含める必要があります。 + + +
+ + + diff --git a/reference/ffi/ctype/getalignment.xml b/reference/ffi/ctype/getalignment.xml new file mode 100644 index 0000000000..d3dbfcb057 --- /dev/null +++ b/reference/ffi/ctype/getalignment.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getAlignment + 説明 + + + + &reftitle.description; + + public intFFI\CType::getAlignment + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getarrayelementtype.xml b/reference/ffi/ctype/getarrayelementtype.xml new file mode 100644 index 0000000000..fd691c14e7 --- /dev/null +++ b/reference/ffi/ctype/getarrayelementtype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getArrayElementType + 説明 + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getArrayElementType + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getarraylength.xml b/reference/ffi/ctype/getarraylength.xml new file mode 100644 index 0000000000..7b1f455a74 --- /dev/null +++ b/reference/ffi/ctype/getarraylength.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getArrayLength + 説明 + + + + &reftitle.description; + + public intFFI\CType::getArrayLength + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getattributes.xml b/reference/ffi/ctype/getattributes.xml new file mode 100644 index 0000000000..0b6cf93d6e --- /dev/null +++ b/reference/ffi/ctype/getattributes.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getAttributes + 説明 + + + + &reftitle.description; + + public intFFI\CType::getAttributes + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getenumkind.xml b/reference/ffi/ctype/getenumkind.xml new file mode 100644 index 0000000000..8bab3fb409 --- /dev/null +++ b/reference/ffi/ctype/getenumkind.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getEnumKind + 説明 + + + + &reftitle.description; + + public intFFI\CType::getEnumKind + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getfuncabi.xml b/reference/ffi/ctype/getfuncabi.xml new file mode 100644 index 0000000000..06d83d082a --- /dev/null +++ b/reference/ffi/ctype/getfuncabi.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncABI + 説明 + + + + &reftitle.description; + + public intFFI\CType::getFuncABI + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getfuncparametercount.xml b/reference/ffi/ctype/getfuncparametercount.xml new file mode 100644 index 0000000000..00a14d8fa4 --- /dev/null +++ b/reference/ffi/ctype/getfuncparametercount.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncParameterCount + 関数型の引数の数を取得する + + + + &reftitle.description; + + public intFFI\CType::getFuncParameterCount + + + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 内部的に保持している関数型の引数の数を返します。 + 内部的に保持している型が関数でない場合、 + FFI\Exception をスローします。 + + + + + + diff --git a/reference/ffi/ctype/getfuncparametertype.xml b/reference/ffi/ctype/getfuncparametertype.xml new file mode 100644 index 0000000000..5cc756172e --- /dev/null +++ b/reference/ffi/ctype/getfuncparametertype.xml @@ -0,0 +1,68 @@ + + + + + + + FFI\CType::getFuncParameterType + 関数の引数の型を取得する + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getFuncParameterType + intindex + + + 内部的に保持している関数型の引数の型を返します。 + + + + + + &reftitle.parameters; + + + index + + + 関数の引数の添字 (ゼロ始まり)。 + + + + + + + + &reftitle.returnvalues; + + 内部的に保持している関数型の引数の型を返します。 + 内部的に保持している型が関数でない場合や、 + 与えられた添字がその関数の引数の範囲外の場合、 + FFI\Exception をスローします。 + + + + + + diff --git a/reference/ffi/ctype/getfuncreturntype.xml b/reference/ffi/ctype/getfuncreturntype.xml new file mode 100644 index 0000000000..a04d715592 --- /dev/null +++ b/reference/ffi/ctype/getfuncreturntype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncReturnType + 説明 + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getFuncReturnType + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getkind.xml b/reference/ffi/ctype/getkind.xml new file mode 100644 index 0000000000..e91cbe308e --- /dev/null +++ b/reference/ffi/ctype/getkind.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getKind + 説明 + + + + &reftitle.description; + + public intFFI\CType::getKind + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getname.xml b/reference/ffi/ctype/getname.xml new file mode 100644 index 0000000000..803191df48 --- /dev/null +++ b/reference/ffi/ctype/getname.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getName + 説明 + + + + &reftitle.description; + + public stringFFI\CType::getName + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getpointertype.xml b/reference/ffi/ctype/getpointertype.xml new file mode 100644 index 0000000000..928e942c98 --- /dev/null +++ b/reference/ffi/ctype/getpointertype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getPointerType + 説明 + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getPointerType + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getsize.xml b/reference/ffi/ctype/getsize.xml new file mode 100644 index 0000000000..da92c3fd31 --- /dev/null +++ b/reference/ffi/ctype/getsize.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getSize + 説明 + + + + &reftitle.description; + + public intFFI\CType::getSize + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getstructfieldnames.xml b/reference/ffi/ctype/getstructfieldnames.xml new file mode 100644 index 0000000000..324b727954 --- /dev/null +++ b/reference/ffi/ctype/getstructfieldnames.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getStructFieldNames + 説明 + + + + &reftitle.description; + + public arrayFFI\CType::getStructFieldNames + + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getstructfieldoffset.xml b/reference/ffi/ctype/getstructfieldoffset.xml new file mode 100644 index 0000000000..b841966592 --- /dev/null +++ b/reference/ffi/ctype/getstructfieldoffset.xml @@ -0,0 +1,67 @@ + + + + + + + FFI\CType::getStructFieldOffset + 説明 + + + + &reftitle.description; + + public intFFI\CType::getStructFieldOffset + stringname + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + + + name + + + + + + + + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/ctype/getstructfieldtype.xml b/reference/ffi/ctype/getstructfieldtype.xml new file mode 100644 index 0000000000..c9e0292e25 --- /dev/null +++ b/reference/ffi/ctype/getstructfieldtype.xml @@ -0,0 +1,67 @@ + + + + + + + FFI\CType::getStructFieldType + 説明 + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getStructFieldType + stringname + + + + + + &warn.undocumented.func; + + + + + &reftitle.parameters; + + + name + + + + + + + + + + + &reftitle.returnvalues; + + + + + + + + diff --git a/reference/ffi/examples.xml b/reference/ffi/examples.xml new file mode 100644 index 0000000000..17aa3261ed --- /dev/null +++ b/reference/ffi/examples.xml @@ -0,0 +1,345 @@ + + + + + + &reftitle.examples; +
+ FFI の基本的な使い方 + + FFI API の詳細に深く立ち入る前に、よくあるタスクに対する FFI API の使い方が + どれほど簡単かを示す例をいくつか見てみましょう。 + + + + これらの例の中には、libc.so.6 を必要とするものがあります。 + それらは、このライブラリが利用できないシステムでは動きません。 + + + + + 共有ライブラリの関数を呼ぶ + +printf("Hello %s!\n", "world"); +?> +]]> + + &example.outputs; + + + + + + + + C の関数のうちのいくつかは、特定の呼び出し規約 (例: __fastcall、 + __stdcall、,__vectorcall など) を必要とすることに注意してください。 + + + + + 関数を呼び出し、構造体を引数経由で返す + +new("struct timeval"); +$tz = $ffi->new("struct timezone"); +// C の gettimeofday() を呼ぶ +var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz))); +// C のデータ構造のフィールドにアクセスする +var_dump($tv->tv_sec); +// C のデータ構造全体を出力する +var_dump($tz); +?> +]]> + + &example.outputs.similar; + + + int(0) + ["tz_dsttime"]=> + int(0) +} +]]> + + + + + + 既存の C の変数にアクセスする + +errno); +?> +]]> + + &example.outputs; + + + + + + + + C の変数を作成して書き換える + +cdata); + +// 単純な代入 +$x->cdata = 5; +var_dump($x->cdata); + +// 複合代入 +$x->cdata += 2; +var_dump($x->cdata); +?> +]]> + + &example.outputs; + + + + + + + + C の配列を扱う + + +]]> + + &example.outputs; + + + + + + + + C の enum を扱う + +ZEND_FFI_SYM_TYPE); +var_dump($a->ZEND_FFI_SYM_CONST); +var_dump($a->ZEND_FFI_SYM_VAR); +?> +]]> + + &example.outputs; + + + + + +
+
+ PHP のコールバック + + PHP のクロージャを、関数ポインタ型のネイティブ変数に代入したり、 + 関数の引数として渡したりできます。 + + PHP の <classname>Closure</classname> を C の関数ポインタに代入する + +zend_write; +$zend->zend_write = function($str, $len) { + global $orig_zend_write; + $orig_zend_write("{\n\t", 3); + $ret = $orig_zend_write($str, $len); + $orig_zend_write("}\n", 2); + return $ret; +}; +echo "Hello World 2!\n"; +$zend->zend_write = $orig_zend_write; +echo "Hello World 3!\n"; +?> +]]> + + &example.outputs; + + + + + これは動作こそしますが、この機能は libffi が動作するすべてのプラットフォームでサポートされているわけではありません。 + また、非効率的であり、リクエストの終了時にリソースがリークします。 + + + したがって、PHP のコールバックの使用は最小限にすることを推奨します。 + + + +
+ +
+ PHP/FFI/事前ロードの完全な例 + + php.ini + + + + preload.php + + +]]> + + dummy.h + + + + dummy.php + +printf($format, ...$args); + } +} +?> +]]> + + test.php + +printf("Hello %s!\n", "world"); +?> +]]> + + +
+ + + diff --git a/reference/ffi/ffi.cdata.xml b/reference/ffi/ffi.cdata.xml new file mode 100644 index 0000000000..a252cc5217 --- /dev/null +++ b/reference/ffi/ffi.cdata.xml @@ -0,0 +1,163 @@ + + + + + + + C のデータハンドル + FFI\CData + + + + +
+ &reftitle.intro; + + FFI\CData オブジェクトは、通常の PHP データのように様々な方法で使用できます: + + + + + スカラー型の C のデータは $cdata プロパティを通してアクセスできます。例: + $x = FFI::new('int'); $x->cdata = 42; + + + + + C の構造体や共用体のフィールドは通常の PHP のオブジェクトプロパティのようにアクセスできます。例: + $cdata->field + + + + + C の配列要素は通常の PHP の配列要素のようにアクセスできます。例: + $cdata[$offset] + + + + + C の配列は &foreach; 文を使って反復できます。 + + + + + C の配列は count の引数として使えます。 + + + + + C のポインタは配列のように参照外しできます。例: $cdata[0] + + + + + C のポインタは通常の比較演算子を使って比較できます (<、 + <=、==、!=、>=、>)。 + + + + + C のポインタは通常の +/-/ + ++/-- 演算子を使ってインクリメント・デクリメントできます。例: $cdata += 5 + + + + + C のポインタは通常の - 演算子を使って他のポインタと引き算できます。 + + + + + C の関数ポインタは通常の PHP のクロージャのように呼び出せます。例: $cdata() + + + + + 任意の C のデータは clone 演算子を使って + 複製できます。例: $cdata2 = clone $cdata; + + + + + 任意の C のデータは var_dump や print_r 等を + 使って可視化できます。 + + + + + PHP 8.3.0 以降、FFI\CData は構造体やフィールドに代入できるようになりました。 + + + + + + 特筆すべき制限として、FFI\CData インスタンスは + isset、empty、unset をサポートしていません。 + また、ラップされた C の構造体や共用体は Traversable を実装していません。 + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI\CData + + + + +
+ +
+ &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI\CData は構造体やフィールドに代入できるようになりました。 + + + + + +
+ + + + + + + diff --git a/reference/ffi/ffi.ctype.xml b/reference/ffi/ffi.ctype.xml new file mode 100644 index 0000000000..9b08167fe9 --- /dev/null +++ b/reference/ffi/ffi.ctype.xml @@ -0,0 +1,565 @@ + + + + + + + C の型ハンドル + FFI\CType + + + + +
+ &reftitle.intro; + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI\CType + + + &Constants; + + public + const + int + FFI\CType::TYPE_VOID + + + public + const + int + FFI\CType::TYPE_FLOAT + + + public + const + int + FFI\CType::TYPE_DOUBLE + + + public + const + int + FFI\CType::TYPE_LONGDOUBLE + + + public + const + int + FFI\CType::TYPE_UINT8 + + + public + const + int + FFI\CType::TYPE_SINT8 + + + public + const + int + FFI\CType::TYPE_UINT16 + + + public + const + int + FFI\CType::TYPE_SINT16 + + + public + const + int + FFI\CType::TYPE_UINT32 + + + public + const + int + FFI\CType::TYPE_SINT32 + + + public + const + int + FFI\CType::TYPE_UINT64 + + + public + const + int + FFI\CType::TYPE_SINT64 + + + public + const + int + FFI\CType::TYPE_ENUM + + + public + const + int + FFI\CType::TYPE_BOOL + + + public + const + int + FFI\CType::TYPE_CHAR + + + public + const + int + FFI\CType::TYPE_POINTER + + + public + const + int + FFI\CType::TYPE_FUNC + + + public + const + int + FFI\CType::TYPE_ARRAY + + + public + const + int + FFI\CType::TYPE_STRUCT + + + public + const + int + FFI\CType::ATTR_CONST + + + public + const + int + FFI\CType::ATTR_INCOMPLETE_TAG + + + public + const + int + FFI\CType::ATTR_VARIADIC + + + public + const + int + FFI\CType::ATTR_INCOMPLETE_ARRAY + + + public + const + int + FFI\CType::ATTR_VLA + + + public + const + int + FFI\CType::ATTR_UNION + + + public + const + int + FFI\CType::ATTR_PACKED + + + public + const + int + FFI\CType::ATTR_MS_STRUCT + + + public + const + int + FFI\CType::ATTR_GCC_STRUCT + + + public + const + int + FFI\CType::ABI_DEFAULT + + + public + const + int + FFI\CType::ABI_CDECL + + + public + const + int + FFI\CType::ABI_FASTCALL + + + public + const + int + FFI\CType::ABI_THISCALL + + + public + const + int + FFI\CType::ABI_STDCALL + + + public + const + int + FFI\CType::ABI_PASCAL + + + public + const + int + FFI\CType::ABI_REGISTER + + + public + const + int + FFI\CType::ABI_MS + + + public + const + int + FFI\CType::ABI_SYSV + + + public + const + int + FFI\CType::ABI_VECTORCALL + + + &Methods; + + + + + + +
+ +
+ &reftitle.constants; + + + FFI\CType::TYPE_VOID + + + + + + + FFI\CType::TYPE_FLOAT + + + + + + + FFI\CType::TYPE_DOUBLE + + + + + + + FFI\CType::TYPE_LONGDOUBLE + + + + + + + FFI\CType::TYPE_UINT8 + + + + + + + FFI\CType::TYPE_SINT8 + + + + + + + FFI\CType::TYPE_UINT16 + + + + + + + FFI\CType::TYPE_SINT16 + + + + + + + FFI\CType::TYPE_UINT32 + + + + + + + FFI\CType::TYPE_SINT32 + + + + + + + FFI\CType::TYPE_UINT64 + + + + + + + FFI\CType::TYPE_SINT64 + + + + + + + FFI\CType::TYPE_ENUM + + + + + + + FFI\CType::TYPE_BOOL + + + + + + + FFI\CType::TYPE_CHAR + + + + + + + FFI\CType::TYPE_POINTER + + + + + + + FFI\CType::TYPE_FUNC + + + + + + + FFI\CType::TYPE_ARRAY + + + + + + + FFI\CType::TYPE_STRUCT + + + + + + + FFI\CType::ATTR_CONST + + + + + + + FFI\CType::ATTR_INCOMPLETE_TAG + + + + + + + FFI\CType::ATTR_VARIADIC + + + + + + + FFI\CType::ATTR_INCOMPLETE_ARRAY + + + + + + + FFI\CType::ATTR_VLA + + + + + + + FFI\CType::ATTR_UNION + + + + + + + FFI\CType::ATTR_PACKED + + + + + + + FFI\CType::ATTR_MS_STRUCT + + + + + + + FFI\CType::ATTR_GCC_STRUCT + + + + + + + FFI\CType::ABI_DEFAULT + + + + + + + FFI\CType::ABI_CDECL + + + + + + + FFI\CType::ABI_FASTCALL + + + + + + + FFI\CType::ABI_THISCALL + + + + + + + FFI\CType::ABI_STDCALL + + + + + + + FFI\CType::ABI_PASCAL + + + + + + + FFI\CType::ABI_REGISTER + + + + + + + FFI\CType::ABI_MS + + + + + + + FFI\CType::ABI_SYSV + + + + + + + FFI\CType::ABI_VECTORCALL + + + + + +
+ + + + &reference.ffi.entities.ctype; + + + diff --git a/reference/ffi/ffi.exception.xml b/reference/ffi/ffi.exception.xml new file mode 100644 index 0000000000..d34b11321a --- /dev/null +++ b/reference/ffi/ffi.exception.xml @@ -0,0 +1,76 @@ + + + + + + + FFI 例外 + FFI\Exception + + + + +
+ &reftitle.intro; + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + FFI\Exception + + + + extends + Error + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + + + diff --git a/reference/ffi/ffi.parserexception.xml b/reference/ffi/ffi.parserexception.xml new file mode 100644 index 0000000000..598a9503ec --- /dev/null +++ b/reference/ffi/ffi.parserexception.xml @@ -0,0 +1,77 @@ + + + + + + + FFI パーサー例外 + FFI\ParserException + + + + +
+ &reftitle.intro; + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI\ParserException + + + + extends + FFI\Exception + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + + + diff --git a/reference/ffi/ffi.xml b/reference/ffi/ffi.xml new file mode 100644 index 0000000000..6fbc6e8064 --- /dev/null +++ b/reference/ffi/ffi.xml @@ -0,0 +1,103 @@ + + + + + + + C のコードやデータへの主要インターフェース + FFI + + + + +
+ &reftitle.intro; + + このクラスのオブジェクトは、ファクトリーメソッドである FFI::cdef や + FFI::load、FFI::scope によって作成されます。 + 定義された C の変数は FFI インスタンスのプロパティとして利用可能となり、 + 定義された C の関数は FFI インスタンスのメソッドとして利用可能となります。 + 宣言された C の型は、FFI::new や FFI::type を使って + 新しい C のデータ構造を作成するのに使用できます。 + + + FFI 定義のパースや共有ライブラリの読み込みには長い時間がかかることがあります。 + Web 環境において、各 HTTP リクエストでこれを行うのは不便です。 + しかし、FFI 定義やライブラリを PHP の起動時に事前ロードし、FFI オブジェクトを必要なときにインスタンス化することが可能です。 + ヘッダーファイルは特殊な define である FFI_SCOPE によって拡張することができ + (例: #define FFI_SCOPE "foo"。デフォルトのスコープは "C" です)、 + 事前ロード中に FFI::load によって読み込むことができます。 + これによって、永続的なバインディングが作成されます。 + こうして作られたバインディングは、FFI::scope を通じて後続する全リクエストで利用可能となります。 + 詳しくは PHP/FFI/事前ロードの完全な例 + を参照してください。 + + + 複数の C のヘッダーファイルを同一のスコープへと事前ロードできます。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI + + + &Constants; + + public + const + int + FFI::__BIGGEST_ALIGNMENT__ + + + &Methods; + + + + + + +
+ +
+ &reftitle.constants; + + + FFI::__BIGGEST_ALIGNMENT__ + + + + + +
+ + + &reference.ffi.entities.ffi; + + + diff --git a/reference/ffi/ffi/addr.xml b/reference/ffi/ffi/addr.xml new file mode 100644 index 0000000000..e9bb00eb90 --- /dev/null +++ b/reference/ffi/ffi/addr.xml @@ -0,0 +1,66 @@ + + + + + + + FFI::addr + C のデータへのアンマネージドなポインターを作成する + + + + &reftitle.description; + + public static FFI\CDataFFI::addr + FFI\CDataptr + + + 与えられた FFI\CData によって表される C のデータへの + アンマネージドなポインターを作成します。元になる ptr + は返されるポインターよりも長く生存しなければなりません。 + この関数は、主に C の関数へ引数をポインタ経由で渡すのに便利です。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータ構造へのポインターのハンドル。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI\CData オブジェクトを返します。 + + + + + diff --git a/reference/ffi/ffi/alignof.xml b/reference/ffi/ffi/alignof.xml new file mode 100644 index 0000000000..c459db90e9 --- /dev/null +++ b/reference/ffi/ffi/alignof.xml @@ -0,0 +1,65 @@ + + + + + + + FFI::alignof + アラインメントを取得する + + + + &reftitle.description; + + public static intFFI::alignof + FFI\CDataFFI\CTypeptr + + + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのアラインメントを返します。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータまたは C の型のハンドル。 + + + + + + + + &reftitle.returnvalues; + + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのアラインメントを返します。 + + + + + diff --git a/reference/ffi/ffi/arraytype.xml b/reference/ffi/ffi/arraytype.xml new file mode 100644 index 0000000000..660e1009da --- /dev/null +++ b/reference/ffi/ffi/arraytype.xml @@ -0,0 +1,84 @@ + + + + + + + FFI::arrayType + 新しい C の配列型を動的に構築する + + + + &reftitle.description; + + public static FFI\CTypeFFI::arrayType + FFI\CTypetype + arraydimensions + + + type で指定された要素型と dimensions で指定された次元を持つ + 新しい C の配列型を動的に構築します。以下の例において $t1 と + $t2 は等しい配列型です。 + + + +]]> + + + + + + + &reftitle.parameters; + + + type + + + 有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。 + + + + + dimensions + + + 型の次元を表す array。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成した FFI\CType オブジェクトを返します。 + + + + + diff --git a/reference/ffi/ffi/cast.xml b/reference/ffi/ffi/cast.xml new file mode 100644 index 0000000000..eebafa64f2 --- /dev/null +++ b/reference/ffi/ffi/cast.xml @@ -0,0 +1,102 @@ + + + + + + + FFI::cast + C の型キャストを実行する + + + + &reftitle.description; + + public FFI\CDatanullFFI::cast + FFI\CTypestringtype + FFI\CDataintfloatboolnullptr + + + FFI::cast は、同じ C のデータ構造を参照するものの別の型が紐付けられた + FFI\CData オブジェクトを新しく作成します。 + 返却されるオブジェクトはその C のデータを所有しません。元の ptr は + その返り値よりも長く生存する必要があります。 + C の型は、有効な C の型宣言を表す string として指定するか、 + 以前作成した FFI\CType オブジェクトとして指定します。 + このインスタンスで宣言された任意の型が使えます。 + + + + + &reftitle.parameters; + + + type + + + 有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。 + + + + + ptr + + + C のデータ構造へのポインターのハンドル。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI\CData オブジェクトを返します。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI::cast を static メソッドとして呼び出すのは非推奨となりました。 + + + + + + + + + + diff --git a/reference/ffi/ffi/cdef.xml b/reference/ffi/ffi/cdef.xml new file mode 100644 index 0000000000..454ce772eb --- /dev/null +++ b/reference/ffi/ffi/cdef.xml @@ -0,0 +1,117 @@ + + + + + + + FFI::cdef + 新しい FFI オブジェクトを作成する + + + + &reftitle.description; + + public static FFIFFI::cdef + stringcode"" + stringnulllib&null; + + + 新しい FFI オブジェクトを作成します。 + + + + + &reftitle.parameters; + + + code + + + 通常の C 言語の宣言 (型、構造体、関数、変数など) を含む文字列。 + 実際には、この文字列は C のヘッダーファイルからコピーペーストしてきたものかもしれません。 + + + + C のプリプロセッサーディレクティブはサポートされていません。 + 例えば、#include や #define、プリプロセッサーマクロは動作しません。 + + + + + + lib + + + 共有ライブラリの名前。 + ここで指定したライブラリが読み込まれ、与えた定義とリンクされます。 + + + + lib を省略したり &null; を渡したりすると、 + RTLD_DEFAULT をサポートしているプラットフォームでは、 + 通常のグローバルスコープから code で宣言されているシンボルを探索しようとします。 + そうでないシステムでは、シンボルの解決に失敗します。 + + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI オブジェクトを返します。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + void を返す C の関数が、FFI\CType::TYPE_VOID + ではなく PHP の null を返すようになりました。 + + + + 8.0.0 + + lib は、nullable になりました。 + + + + + + + + + diff --git a/reference/ffi/ffi/free.xml b/reference/ffi/ffi/free.xml new file mode 100644 index 0000000000..f41081400e --- /dev/null +++ b/reference/ffi/ffi/free.xml @@ -0,0 +1,63 @@ + + + + + + + FFI::free + アンマネージドなデータ構造を解放する + + + + &reftitle.description; + + public static voidFFI::free + FFI\CDataptr + + + 以前に作成されたアンマネージドなデータ構造を手で解放します。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータ構造へのアンマネージドなポインターのハンドル。 + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/isnull.xml b/reference/ffi/ffi/isnull.xml new file mode 100644 index 0000000000..fa514d8d75 --- /dev/null +++ b/reference/ffi/ffi/isnull.xml @@ -0,0 +1,63 @@ + + + + + + + FFI::isNull + FFI\CData が NULL ポインターかどうかを調べる + + + + &reftitle.description; + + public static boolFFI::isNull + FFI\CDataptr + + + FFI\CData が NULL ポインターかどうかを調べます。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータ構造へのポインターのハンドル。 + + + + + + + + &reftitle.returnvalues; + + FFI\CData が NULL ポインターかどうかを返します。 + + + + + diff --git a/reference/ffi/ffi/load.xml b/reference/ffi/ffi/load.xml new file mode 100644 index 0000000000..5aa07088c5 --- /dev/null +++ b/reference/ffi/ffi/load.xml @@ -0,0 +1,118 @@ + + + + + + + FFI::load + C のヘッダーファイルから C の宣言を読み込む + + + + &reftitle.description; + + public static FFInullFFI::load + stringfilename + + + C のヘッダーファイルから C の宣言を読み込みます。 + 読み込まれる C のヘッダーファイル内で特殊な define FFI_LIB を使うことで、 + 読み込む共有ライブラリを指定することが可能です。 + + + + + &reftitle.parameters; + + + filename + + + C のヘッダーファイル名。 + + + C のプリプロセッサーディレクティブはサポートされていません。 + 例えば、#include や #define、プリプロセッサーマクロは動作しません。 + ただし、次に挙げる特殊な場合を除きます。 + + + このヘッダーファイルでは、#define 文で + FFI_SCOPE 変数を定義すべきです + (例: #define FFI_SCOPE "MYLIB")。 + 詳しくは FFI クラスの概要 を参照してください。 + + + このヘッダーファイルでは、#define 文で + FFI_LIB 変数を定義することで、公開するライブラリを指定しても構いません。 + それがシステムライブラリなら、必要なのはファイル名だけです (例: #define FFI_LIB + "libc.so.6")。カスタムライブラリなら、相対パスが必要です + (例: #define FFI_LIB "./mylib.so")。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI オブジェクトを返します。 + 失敗時には &null; を返します。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + 現在のシステムユーザが opcache.preload_user + 設定ディレクティブで定義されたユーザと同じである場合、 + 事前ロードスクリプト の中で + FFI::load を呼べるようになりました。 + + + + + + + + + &reftitle.seealso; + + + FFI::scope + + + + + + diff --git a/reference/ffi/ffi/memcmp.xml b/reference/ffi/ffi/memcmp.xml new file mode 100644 index 0000000000..ebb4aa044e --- /dev/null +++ b/reference/ffi/ffi/memcmp.xml @@ -0,0 +1,90 @@ + + + + + + + FFI::memcmp + メモリ領域を比較する + + + + &reftitle.description; + + public static intFFI::memcmp + stringFFI\CDataptr1 + stringFFI\CDataptr2 + intsize + + + メモリ領域 ptr1 と ptr2 を + size バイト分比較します。 + ptr1 も ptr2 も、 + ネイティブデータ構造 (FFI\CData) または + PHP の string にできます。 + + + + + &reftitle.parameters; + + + ptr1 + + + 一方のメモリ領域の開始位置。 + + + + + ptr2 + + + もう一方のメモリ領域の開始位置。 + + + + + size + + + 比較するバイト数。 + + + + + + + + &reftitle.returnvalues; + + ptr1 から始まるメモリ領域の中身が + ptr2 から始まるメモリ領域の中身より小さければ、 + 0 より小さい値を返します。 + ptr1 が ptr2 より大きければ、 + 0 より大きい値を返します。 + 両者が等しければ 0 を返します。 + + + + + diff --git a/reference/ffi/ffi/memcpy.xml b/reference/ffi/ffi/memcpy.xml new file mode 100644 index 0000000000..55bacdf808 --- /dev/null +++ b/reference/ffi/ffi/memcpy.xml @@ -0,0 +1,82 @@ + + + + + + + FFI::memcpy + あるメモリ領域を別の領域へコピーする + + + + &reftitle.description; + + public static voidFFI::memcpy + FFI\CDatato + FFI\CDatastringfrom + intsize + + + from のメモリ領域から size バイト分を + to のメモリ領域へとコピーします。 + + + + + &reftitle.parameters; + + + to + + + コピー先のメモリ領域の開始位置。 + + + + + from + + + コピー元のメモリ領域の開始位置。 + + + + + size + + + コピーするバイト数。 + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/memset.xml b/reference/ffi/ffi/memset.xml new file mode 100644 index 0000000000..fb773b05db --- /dev/null +++ b/reference/ffi/ffi/memset.xml @@ -0,0 +1,82 @@ + + + + + + + FFI::memset + メモリ領域を埋める + + + + &reftitle.description; + + public static voidFFI::memset + FFI\CDataptr + intvalue + intsize + + + ptr が指すメモリ領域を size バイト分 + 与えられた value で埋めます。 + + + + + &reftitle.parameters; + + + ptr + + + 埋めるメモリ領域の開始位置。 + + + + + value + + + 埋めるのに使うバイト。 + + + + + size + + + 埋めるバイト数。 + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/new.xml b/reference/ffi/ffi/new.xml new file mode 100644 index 0000000000..c8b3169977 --- /dev/null +++ b/reference/ffi/ffi/new.xml @@ -0,0 +1,112 @@ + + + + + + + FFI::new + C のデータ構造を作成する + + + + &reftitle.description; + + public FFI\CDatanullFFI::new + FFI\CTypestringtype + boolowned&true; + boolpersistent&false; + + + 与えられた C の型を持つネイティブデータ構造を作成します。 + このインスタンスで宣言された任意の型が使えます。 + + + + + &reftitle.parameters; + + + type + + + type は、有効な C の宣言を表す string か、 + 作成済みの FFI\CType のインスタンスです。 + + + + + owned + + + 所有された (マネージドな) データを作成するか、アンマネージドなデータを作成するか。 + マネージドデータは返される FFI\CData オブジェクトと共に生存し、 + そのオブジェクトへの最後の参照が PHP の通常のリファレンスカウントや GC によって解放されたときに解放されます。 + アンマネージドなデータは、不要になったら FFI::free を呼んで解放すべきです。 + + + + + persistent + + + この C のデータ構造をシステムヒープ上に永続的に確保するか (malloc を使用)、 + PHP のリクエストヒープ上に確保するか (emalloc を使用)。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI\CData オブジェクトを返します。 + 失敗時には &null; を返します。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI::new を static メソッドとして呼び出すのは非推奨となりました。 + + + + + + + + + + diff --git a/reference/ffi/ffi/scope.xml b/reference/ffi/ffi/scope.xml new file mode 100644 index 0000000000..8bc7c6308e --- /dev/null +++ b/reference/ffi/ffi/scope.xml @@ -0,0 +1,76 @@ + + + + + + + FFI::scope + 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する + + + + &reftitle.description; + + public static FFIFFI::scope + stringname + + + 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化します。 + + + FFI::scope メソッドを同じスコープに対して複数回呼んでも安全です。 + 同じスコープを指す複数の参照は同時に読み込まれるかもしれません。 + + + + + &reftitle.parameters; + + + name + + + 特殊な FFI_SCOPE define によって定義されたスコープ名。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI オブジェクトを返します。 + + + + + &reftitle.seealso; + + + FFI::load + + + + + + diff --git a/reference/ffi/ffi/sizeof.xml b/reference/ffi/ffi/sizeof.xml new file mode 100644 index 0000000000..5dff77d9e4 --- /dev/null +++ b/reference/ffi/ffi/sizeof.xml @@ -0,0 +1,64 @@ + + + + + + + FFI::sizeof + C のデータサイズまたは C の型サイズを取得する + + + + &reftitle.description; + + public static intFFI::sizeof + FFI\CDataFFI\CTypeptr + + + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのサイズを返します。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータまたは C の型のハンドル。 + + + + + + + + &reftitle.returnvalues; + + ptr が指すメモリ領域のサイズ。 + + + + + diff --git a/reference/ffi/ffi/string.xml b/reference/ffi/ffi/string.xml new file mode 100644 index 0000000000..791af9f83b --- /dev/null +++ b/reference/ffi/ffi/string.xml @@ -0,0 +1,98 @@ + + + + + + + FFI::string + メモリ領域から PHP の文字列を作成する + + + + &reftitle.description; + + public static stringFFI::string + FFI\CDataptr + intnullsize&null; + + + ptr が指すメモリ領域の size バイト分から + PHP の string を作成します。 + + + + + &reftitle.parameters; + + + ptr + + + string を作成する元となるメモリ領域の開始位置。 + + + + + size + + + string へコピーするバイト数。 + size を省略したり &null; を指定したりする場合、 + ptr はゼロ終端された C の char 配列でなければなりません。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された PHP の string。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.0.0 + + size が nullable になりました。以前は + 0 がデフォルトでした。 + + + + + + + + + diff --git a/reference/ffi/ffi/type.xml b/reference/ffi/ffi/type.xml new file mode 100644 index 0000000000..fa3eba2d51 --- /dev/null +++ b/reference/ffi/ffi/type.xml @@ -0,0 +1,91 @@ + + + + + + + FFI::type + C の宣言から FFI\CType オブジェクトを作成する + + + + &reftitle.description; + + public FFI\CTypenullFFI::type + stringtype + + + この関数は、C の型宣言を持つ string を渡すと、 + 与えられた string に対応する + FFI\CType オブジェクトを作成して返します。 + このインスタンスで宣言された任意の型が使えます。 + + + + + &reftitle.parameters; + + + type + + + 有効な C の宣言を持つ string。 + + + + + + + + &reftitle.returnvalues; + + 新しく作成された FFI\CType オブジェクトを返します。 + 失敗時には &null; を返します。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI::type を static メソッドとして呼び出すのは非推奨となりました。 + + + + + + + + + + diff --git a/reference/ffi/ffi/typeof.xml b/reference/ffi/ffi/typeof.xml new file mode 100644 index 0000000000..9e03f07a85 --- /dev/null +++ b/reference/ffi/ffi/typeof.xml @@ -0,0 +1,65 @@ + + + + + + + FFI::typeof + FFI\CData の FFI\CType を取得する + + + + &reftitle.description; + + public static FFI\CTypeFFI::typeof + FFI\CDataptr + + + 与えられた FFI\CData オブジェクトの型を表す + FFI\CType オブジェクトを取得します。 + + + + + &reftitle.parameters; + + + ptr + + + C のデータ構造へのポインターのハンドル。 + + + + + + + + &reftitle.returnvalues; + + 与えられた FFI\CData オブジェクトの型を表す + FFI\CType オブジェクトを返します。 + + + + + diff --git a/reference/ffi/setup.xml b/reference/ffi/setup.xml new file mode 100644 index 0000000000..de9a9a6bbf --- /dev/null +++ b/reference/ffi/setup.xml @@ -0,0 +1,118 @@ + + + + + + &reftitle.setup; + +
+ &reftitle.required; + + この拡張には、libffi library の + インストールが必要です。 + +
+ + + &reference.ffi.configure; + + +
+ &reftitle.runtime; + &extension.runtime; + + + FFI &ConfigureOptions; + + + + &Name; + &Default; + &Changeable; + &Changelog; + + + + + ffi.enable + "preload" + INI_SYSTEM + + + + ffi.preload + "" + INI_SYSTEM + + + + +
+ &ini.php.constants; + + + &ini.descriptions.title; + + + + + + ffi.enable + string + + + + FFI API の使用を有効化する ("true") か + 無効化する ("false") か、 + CLI SAPI と事前ロードファイルでだけ使えるよう制限する ("preload") かを + 指定します。 + + + FFI API の利用制限は、FFI クラスにのみ影響し、 + FFI\CData オブジェクトのオーバーロードされた関数には影響しません。 + つまり、事前ロードファイルで FFI\CData オブジェクトを作成し、 + それを PHP スクリプトで直接使うことは可能だということです。 + + + + + + ffi.preload + string + + + + FFI バインディングを起動時に事前ロードできるようにします。 + opcache.preload_user が設定されている場合、 + FFI の事前ロードを FFI::load で実現することはできません。 + このディレクティブは DIRECTORY_SEPARATOR で区切られたファイル名のリストを受け付けます。 + 事前ロードされたバインディングは FFI::scope を呼ぶことでアクセスできます。 + + + + + +
+ + + +