From b53e60dc2d4fe2327b4e0bc0e335b61632ed520c Mon Sep 17 00:00:00 2001 From: nsfisis Date: Mon, 13 Oct 2025 17:31:29 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=E6=9C=AA=E8=A8=B3=E3=83=95=E3=82=A1?= =?UTF-8?q?=E3=82=A4=E3=83=AB=20reference/ffi/**/*.xml=20=E3=82=92?= =?UTF-8?q?=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reference/ffi/book.xml | 73 +++ reference/ffi/configure.xml | 40 ++ reference/ffi/ctype/getalignment.xml | 58 ++ reference/ffi/ctype/getarrayelementtype.xml | 58 ++ reference/ffi/ctype/getarraylength.xml | 58 ++ reference/ffi/ctype/getattributes.xml | 58 ++ reference/ffi/ctype/getenumkind.xml | 58 ++ reference/ffi/ctype/getfuncabi.xml | 58 ++ reference/ffi/ctype/getfuncparametercount.xml | 58 ++ reference/ffi/ctype/getfuncparametertype.xml | 68 +++ reference/ffi/ctype/getfuncreturntype.xml | 58 ++ reference/ffi/ctype/getkind.xml | 58 ++ reference/ffi/ctype/getname.xml | 58 ++ reference/ffi/ctype/getpointertype.xml | 58 ++ reference/ffi/ctype/getsize.xml | 58 ++ reference/ffi/ctype/getstructfieldnames.xml | 58 ++ reference/ffi/ctype/getstructfieldoffset.xml | 67 +++ reference/ffi/ctype/getstructfieldtype.xml | 67 +++ reference/ffi/examples.xml | 345 +++++++++++ reference/ffi/ffi.cdata.xml | 163 +++++ reference/ffi/ffi.ctype.xml | 565 ++++++++++++++++++ reference/ffi/ffi.exception.xml | 76 +++ reference/ffi/ffi.parserexception.xml | 77 +++ reference/ffi/ffi.xml | 101 ++++ reference/ffi/ffi/addr.xml | 65 ++ reference/ffi/ffi/alignof.xml | 65 ++ reference/ffi/ffi/arraytype.xml | 85 +++ reference/ffi/ffi/cast.xml | 102 ++++ reference/ffi/ffi/cdef.xml | 117 ++++ reference/ffi/ffi/free.xml | 63 ++ reference/ffi/ffi/isnull.xml | 63 ++ reference/ffi/ffi/load.xml | 115 ++++ reference/ffi/ffi/memcmp.xml | 87 +++ reference/ffi/ffi/memcpy.xml | 82 +++ reference/ffi/ffi/memset.xml | 82 +++ reference/ffi/ffi/new.xml | 113 ++++ reference/ffi/ffi/scope.xml | 76 +++ reference/ffi/ffi/sizeof.xml | 64 ++ reference/ffi/ffi/string.xml | 98 +++ reference/ffi/ffi/type.xml | 90 +++ reference/ffi/ffi/typeof.xml | 65 ++ reference/ffi/setup.xml | 116 ++++ 42 files changed, 3944 insertions(+) create mode 100644 reference/ffi/book.xml create mode 100644 reference/ffi/configure.xml create mode 100644 reference/ffi/ctype/getalignment.xml create mode 100644 reference/ffi/ctype/getarrayelementtype.xml create mode 100644 reference/ffi/ctype/getarraylength.xml create mode 100644 reference/ffi/ctype/getattributes.xml create mode 100644 reference/ffi/ctype/getenumkind.xml create mode 100644 reference/ffi/ctype/getfuncabi.xml create mode 100644 reference/ffi/ctype/getfuncparametercount.xml create mode 100644 reference/ffi/ctype/getfuncparametertype.xml create mode 100644 reference/ffi/ctype/getfuncreturntype.xml create mode 100644 reference/ffi/ctype/getkind.xml create mode 100644 reference/ffi/ctype/getname.xml create mode 100644 reference/ffi/ctype/getpointertype.xml create mode 100644 reference/ffi/ctype/getsize.xml create mode 100644 reference/ffi/ctype/getstructfieldnames.xml create mode 100644 reference/ffi/ctype/getstructfieldoffset.xml create mode 100644 reference/ffi/ctype/getstructfieldtype.xml create mode 100644 reference/ffi/examples.xml create mode 100644 reference/ffi/ffi.cdata.xml create mode 100644 reference/ffi/ffi.ctype.xml create mode 100644 reference/ffi/ffi.exception.xml create mode 100644 reference/ffi/ffi.parserexception.xml create mode 100644 reference/ffi/ffi.xml create mode 100644 reference/ffi/ffi/addr.xml create mode 100644 reference/ffi/ffi/alignof.xml create mode 100644 reference/ffi/ffi/arraytype.xml create mode 100644 reference/ffi/ffi/cast.xml create mode 100644 reference/ffi/ffi/cdef.xml create mode 100644 reference/ffi/ffi/free.xml create mode 100644 reference/ffi/ffi/isnull.xml create mode 100644 reference/ffi/ffi/load.xml create mode 100644 reference/ffi/ffi/memcmp.xml create mode 100644 reference/ffi/ffi/memcpy.xml create mode 100644 reference/ffi/ffi/memset.xml create mode 100644 reference/ffi/ffi/new.xml create mode 100644 reference/ffi/ffi/scope.xml create mode 100644 reference/ffi/ffi/sizeof.xml create mode 100644 reference/ffi/ffi/string.xml create mode 100644 reference/ffi/ffi/type.xml create mode 100644 reference/ffi/ffi/typeof.xml create mode 100644 reference/ffi/setup.xml diff --git a/reference/ffi/book.xml b/reference/ffi/book.xml new file mode 100644 index 0000000000..25d7502401 --- /dev/null +++ b/reference/ffi/book.xml @@ -0,0 +1,73 @@ + + + + + + + Foreign Function Interface + FFI + + + &reftitle.intro; + + This extension allows the loading of shared libraries (.DLL or + .so), calling of C functions and accessing of C data structures + in pure PHP, without having to have deep knowledge of the Zend extension API, and + without having to learn a third “intermediate” language. + The public API is implemented as a single class FFI with + several static methods (some of them may be called dynamically), and overloaded object + methods, which perform the actual interaction with C data. + + + + FFI is dangerous, since it allows to interface with the system on a very low level. + The FFI extension should only be used by developers having a working knowledge of C + and the used C APIs. To minimize the risk, the FFI API usage may be restricted + with the ffi.enable &php.ini; directive. + + + + + The FFI extension does not render the classic PHP extension API obsolete; it is merely + provided for ad-hoc interfacing with C functions and data structures. + + + + + Currently, accessing FFI data structures is significantly (about 2 times) slower + than accessing native PHP arrays and objects. Therefore, it makes no sense to use + the FFI extension for speed; however, it may make sense to use it to reduce memory + consumption. + + + + + &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..9d0da42da9 --- /dev/null +++ b/reference/ffi/configure.xml @@ -0,0 +1,40 @@ + + + + +
+ &reftitle.install; + + + To enable the FFI extension, PHP has to be configured with + . + + + + Windows users have to include php_ffi.dll into &php.ini; + to enable the FFI extension. + + +
+ + + diff --git a/reference/ffi/ctype/getalignment.xml b/reference/ffi/ctype/getalignment.xml new file mode 100644 index 0000000000..e139ba8c30 --- /dev/null +++ b/reference/ffi/ctype/getalignment.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getAlignment + Description + + + + &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..da69aa13b2 --- /dev/null +++ b/reference/ffi/ctype/getarrayelementtype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getArrayElementType + Description + + + + &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..d953f0bdec --- /dev/null +++ b/reference/ffi/ctype/getarraylength.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getArrayLength + Description + + + + &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..d18a2ef434 --- /dev/null +++ b/reference/ffi/ctype/getattributes.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getAttributes + Description + + + + &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..3b8d53b23d --- /dev/null +++ b/reference/ffi/ctype/getenumkind.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getEnumKind + Description + + + + &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..138a3268e2 --- /dev/null +++ b/reference/ffi/ctype/getfuncabi.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncABI + Description + + + + &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..8618fb6e9b --- /dev/null +++ b/reference/ffi/ctype/getfuncparametercount.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncParameterCount + Retrieve the count of parameters of a function type + + + + &reftitle.description; + + public intFFI\CType::getFuncParameterCount + + + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the number of parameters for the underlying function type. + If the underlying type is not a function, an + FFI\Exception is thrown. + + + + + + diff --git a/reference/ffi/ctype/getfuncparametertype.xml b/reference/ffi/ctype/getfuncparametertype.xml new file mode 100644 index 0000000000..973e081eac --- /dev/null +++ b/reference/ffi/ctype/getfuncparametertype.xml @@ -0,0 +1,68 @@ + + + + + + + FFI\CType::getFuncParameterType + Retrieve the type of a function parameter + + + + &reftitle.description; + + public FFI\CTypeFFI\CType::getFuncParameterType + intindex + + + Returns the type of a parameter for the underlying function type. + + + + + + &reftitle.parameters; + + + index + + + Index of the function parameter, zero-based. + + + + + + + + &reftitle.returnvalues; + + Returns the type of a parameter for the underlying function type. + If the underlying type is not a function, or the given index is outside + of the range of parameters of the function, an + FFI\Exception is thrown. + + + + + + diff --git a/reference/ffi/ctype/getfuncreturntype.xml b/reference/ffi/ctype/getfuncreturntype.xml new file mode 100644 index 0000000000..ab89eb4df2 --- /dev/null +++ b/reference/ffi/ctype/getfuncreturntype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getFuncReturnType + Description + + + + &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..479586f17e --- /dev/null +++ b/reference/ffi/ctype/getkind.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getKind + Description + + + + &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..f1e1cca175 --- /dev/null +++ b/reference/ffi/ctype/getname.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getName + Description + + + + &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..cb511fa048 --- /dev/null +++ b/reference/ffi/ctype/getpointertype.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getPointerType + Description + + + + &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..70fa540e0a --- /dev/null +++ b/reference/ffi/ctype/getsize.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getSize + Description + + + + &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..04597bf021 --- /dev/null +++ b/reference/ffi/ctype/getstructfieldnames.xml @@ -0,0 +1,58 @@ + + + + + + + FFI\CType::getStructFieldNames + Description + + + + &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..febea29ba3 --- /dev/null +++ b/reference/ffi/ctype/getstructfieldoffset.xml @@ -0,0 +1,67 @@ + + + + + + + FFI\CType::getStructFieldOffset + Description + + + + &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..9a2d0cc3cd --- /dev/null +++ b/reference/ffi/ctype/getstructfieldtype.xml @@ -0,0 +1,67 @@ + + + + + + + FFI\CType::getStructFieldType + Description + + + + &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..eedebfb82d --- /dev/null +++ b/reference/ffi/examples.xml @@ -0,0 +1,345 @@ + + + + + + &reftitle.examples; +
+ Basic FFI usage + + Before diving into the details of the FFI API, lets take a look at a few examples + demonstrating the simplicity of the FFI API usage for regular tasks. + + + + Some of these examples require libc.so.6 and as such will + not work on systems where it is not available. + + + + + Calling a function from shared library + +printf("Hello %s!\n", "world"); +?> +]]> + + &example.outputs; + + + + + + + + Note that some C functions need specific calling conventions, e.g. __fastcall, + __stdcall or ,__vectorcall. + + + + + Calling a function, returning a structure through an argument + +new("struct timeval"); +$tz = $ffi->new("struct timezone"); +// call C's gettimeofday() +var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz))); +// access field of C data structure +var_dump($tv->tv_sec); +// print the whole C data structure +var_dump($tz); +?> +]]> + + &example.outputs.similar; + + + int(0) + ["tz_dsttime"]=> + int(0) +} +]]> + + + + + + Accessing existing C variables + +errno); +?> +]]> + + &example.outputs; + + + + + + + + Creating and Modifying C variables + +cdata); + +// simple assignment +$x->cdata = 5; +var_dump($x->cdata); + +// compound assignment +$x->cdata += 2; +var_dump($x->cdata); +?> +]]> + + &example.outputs; + + + + + + + + Working with C arrays + + +]]> + + &example.outputs; + + + + + + + + Working with C enums + +ZEND_FFI_SYM_TYPE); +var_dump($a->ZEND_FFI_SYM_CONST); +var_dump($a->ZEND_FFI_SYM_VAR); +?> +]]> + + &example.outputs; + + + + + +
+
+ PHP Callbacks + + It is possible to assign a PHP closure to a native variable of function pointer type + or to pass it as a function argument: + + Assigning a PHP <classname>Closure</classname> to a C function pointer + +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; + + + + + Although this works, this functionality is not supported on all libffi platforms, is not efficient + and leaks resources by the end of request. + + + It is therefore recommended to minimize the usage of PHP callbacks. + + + +
+ +
+ A Complete PHP/FFI/preloading Example + + 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..237d7d2edb --- /dev/null +++ b/reference/ffi/ffi.cdata.xml @@ -0,0 +1,163 @@ + + + + + + + C Data Handles + FFI\CData + + + + +
+ &reftitle.intro; + + FFI\CData objects can be used in a number of ways as a regular + + PHP data: + + + + C data of scalar types can be read and assigned via the $cdata property, e.g. + $x = FFI::new('int'); $x->cdata = 42; + + + + + C struct and union fields can be accessed as regular PHP object property, e.g. + $cdata->field + + + + + C array elements can be accessed as regular PHP array elements, e.g. + $cdata[$offset] + + + + + C arrays can be iterated using &foreach; statements. + + + + + C arrays can be used as arguments of count. + + + + + C pointers can be dereferenced as arrays, e.g. $cdata[0] + + + + + C pointers can be compared using regular comparison operators (<, + <=, ==, !=, >=, >). + + + + + C pointers can be incremented and decremented using regular +/-/ + ++/-- operations, e.g. $cdata += 5 + + + + + C pointers can be subtracted from another using regular - operations. + + + + + C pointers to functions can be called as a regular PHP closure, e.g. $cdata() + + + + + Any C data can be duplicated using the clone + operator, e.g. $cdata2 = clone $cdata; + + + + + Any C data can be visualized using var_dump, print_r, etc. + + + + + FFI\CData can now be assigned to structs and fields as of PHP 8.3.0. + + + + + + Notable limitations are that FFI\CData instances do not support + isset, empty and unset, + and that wrapped C structs and unions do not implement Traversable. + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI\CData + + + + +
+ +
+ &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI\CData can now be assigned to structs and fields. + + + + + +
+ + + + + + + diff --git a/reference/ffi/ffi.ctype.xml b/reference/ffi/ffi.ctype.xml new file mode 100644 index 0000000000..d3d66049a5 --- /dev/null +++ b/reference/ffi/ffi.ctype.xml @@ -0,0 +1,565 @@ + + + + + + + C Type Handles + 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..a6db36a1e1 --- /dev/null +++ b/reference/ffi/ffi.exception.xml @@ -0,0 +1,76 @@ + + + + + + + FFI Exceptions + 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..a9e49a0308 --- /dev/null +++ b/reference/ffi/ffi.parserexception.xml @@ -0,0 +1,77 @@ + + + + + + + FFI Parser Exceptions + 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..6f295c38c9 --- /dev/null +++ b/reference/ffi/ffi.xml @@ -0,0 +1,101 @@ + + + + + + + Main interface to C code and data + FFI + + + + +
+ &reftitle.intro; + + Objects of this class are created by the factory methods FFI::cdef, + FFI::load or FFI::scope. Defined C variables + are made available as properties of the FFI instance, and defined C functions are made available + as methods of the FFI instance. Declared C types can be used to create new C data structures + using FFI::new and FFI::type. + + + FFI definition parsing and shared library loading may take significant time. It is not useful + to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions + and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files + may be extended with special FFI_SCOPE defines (e.g. #define FFI_SCOPE "foo"; + the default scope is "C") and then loaded by FFI::load during preloading. + This leads to the creation of a persistent binding, that will be available to all the following + requests through FFI::scope. + Refer to the complete PHP/FFI/preloading example + for details. + + + It is possible to preload more than one C header file into the same scope. + +
+ + +
+ &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..bcb09b7e41 --- /dev/null +++ b/reference/ffi/ffi/addr.xml @@ -0,0 +1,65 @@ + + + + + + + FFI::addr + Creates an unmanaged pointer to C data + + + + &reftitle.description; + + public static FFI\CDataFFI::addr + FFI\CDataptr + + + Creates an unmanaged pointer to the C data represented by the given + FFI\CData. The source ptr must survive the + resulting pointer. This function is mainly useful to pass arguments to C functions by pointer. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the pointer to a C data structure. + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI\CData object. + + + + + diff --git a/reference/ffi/ffi/alignof.xml b/reference/ffi/ffi/alignof.xml new file mode 100644 index 0000000000..325883abf1 --- /dev/null +++ b/reference/ffi/ffi/alignof.xml @@ -0,0 +1,65 @@ + + + + + + + FFI::alignof + Gets the alignment + + + + &reftitle.description; + + public static intFFI::alignof + FFI\CDataFFI\CTypeptr + + + Gets the alignment of the given FFI\CData or + FFI\CType object. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the C data or type. + + + + + + + + &reftitle.returnvalues; + + Returns the alignment of the given FFI\CData or + FFI\CType object. + + + + + diff --git a/reference/ffi/ffi/arraytype.xml b/reference/ffi/ffi/arraytype.xml new file mode 100644 index 0000000000..ed0807fb7e --- /dev/null +++ b/reference/ffi/ffi/arraytype.xml @@ -0,0 +1,85 @@ + + + + + + + FFI::arrayType + Dynamically constructs a new C array type + + + + &reftitle.description; + + public static FFI\CTypeFFI::arrayType + FFI\CTypetype + arraydimensions + + + Dynamically constructs a new C array type with elements of type defined by type, + and dimensions specified by dimensions. In the following example $t1 + and $t2 are equivalent array types: + + + +]]> + + + + + + + &reftitle.parameters; + + + type + + + A valid C declaration as string, or an instance of FFI\CType + which has already been created. + + + + + dimensions + + + The dimensions of the type as array. + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI\CType object. + + + + + diff --git a/reference/ffi/ffi/cast.xml b/reference/ffi/ffi/cast.xml new file mode 100644 index 0000000000..107fac3fd9 --- /dev/null +++ b/reference/ffi/ffi/cast.xml @@ -0,0 +1,102 @@ + + + + + + + FFI::cast + Performs a C type cast + + + + &reftitle.description; + + public FFI\CDatanullFFI::cast + FFI\CTypestringtype + FFI\CDataintfloatboolnullptr + + + FFI::cast creates a new FFI\CData + object, that references the same C data structure, but is associated with a different type. + The resulting object does not own the C data, and the source ptr + must survive the result. The C type may be specified as a string with any + valid C type declaration or as FFI\CType object, created before. + Any type declared for the instance is allowed. + + + + + &reftitle.parameters; + + + type + + + A valid C declaration as string, or an instance of FFI\CType + which has already been created. + + + + + ptr + + + The handle of the pointer to a C data structure. + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI\CData object. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + Calling FFI::cast statically is now deprecated. + + + + + + + + + + diff --git a/reference/ffi/ffi/cdef.xml b/reference/ffi/ffi/cdef.xml new file mode 100644 index 0000000000..3305dd2ccc --- /dev/null +++ b/reference/ffi/ffi/cdef.xml @@ -0,0 +1,117 @@ + + + + + + + FFI::cdef + Creates a new FFI object + + + + &reftitle.description; + + public static FFIFFI::cdef + stringcode"" + stringnulllib&null; + + + Creates a new FFI object. + + + + + &reftitle.parameters; + + + code + + + A string containing a sequence of declarations in regular C language + (types, structures, functions, variables, etc). Actually, this string may + be copy-pasted from C header files. + + + + C preprocessor directives are not supported, i.e. #include, + #define and CPP macros do not work. + + + + + + lib + + + The name of a shared library file, to be loaded and linked with the + definitions. + + + + If lib is omitted or &null;, platforms supporting RTLD_DEFAULT + attempt to lookup symbols declared in code in the normal global + scope. Other systems will fail to resolve these symbols. + + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI object. + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + C functions returning void return a PHP null + instead of FFI\CType::TYPE_VOID. + + + + 8.0.0 + + lib is nullable now. + + + + + + + + + diff --git a/reference/ffi/ffi/free.xml b/reference/ffi/ffi/free.xml new file mode 100644 index 0000000000..1616761c65 --- /dev/null +++ b/reference/ffi/ffi/free.xml @@ -0,0 +1,63 @@ + + + + + + + FFI::free + Releases an unmanaged data structure + + + + &reftitle.description; + + public static voidFFI::free + FFI\CDataptr + + + Manually releases a previously created unmanaged data structure. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the unmanaged pointer to a C data structure. + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/isnull.xml b/reference/ffi/ffi/isnull.xml new file mode 100644 index 0000000000..75cd4b327a --- /dev/null +++ b/reference/ffi/ffi/isnull.xml @@ -0,0 +1,63 @@ + + + + + + + FFI::isNull + Checks whether a FFI\CData is a null pointer + + + + &reftitle.description; + + public static boolFFI::isNull + FFI\CDataptr + + + Checks whether a FFI\CData is a null pointer. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the pointer to a C data structure. + + + + + + + + &reftitle.returnvalues; + + Returns whether a FFI\CData is a null pointer. + + + + + diff --git a/reference/ffi/ffi/load.xml b/reference/ffi/ffi/load.xml new file mode 100644 index 0000000000..2359021c11 --- /dev/null +++ b/reference/ffi/ffi/load.xml @@ -0,0 +1,115 @@ + + + + + + + FFI::load + Loads C declarations from a C header file + + + + &reftitle.description; + + public static FFInullFFI::load + stringfilename + + + Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, + using special FFI_LIB defines in the loaded C header file. + + + + + &reftitle.parameters; + + + filename + + + The name of a C header file. + + + C preprocessor directives are not supported, i.e. #include, + #define and CPP macros do not work, except for special cases + listed below. + + + The header file should contain a #define statement for the + FFI_SCOPE variable, e.g.: #define FFI_SCOPE "MYLIB". + Refer to the class introduction for details. + + + The header file may contain a #define statement for the + FFI_LIB variable to specify the library it exposes. If it is + a system library only the file name is required, e.g.: #define FFI_LIB + "libc.so.6". If it is a custom library, a relative path is required, + e.g.: #define FFI_LIB "./mylib.so". + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI object, or &null; on failure. + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI::load is now allowed in + preload scripts when the + current system user is the same as the one defined in the + opcache.preload_user configuration directive. + + + + + + + + + &reftitle.seealso; + + + FFI::scope + + + + + + diff --git a/reference/ffi/ffi/memcmp.xml b/reference/ffi/ffi/memcmp.xml new file mode 100644 index 0000000000..7e29a6b485 --- /dev/null +++ b/reference/ffi/ffi/memcmp.xml @@ -0,0 +1,87 @@ + + + + + + + FFI::memcmp + Compares memory areas + + + + &reftitle.description; + + public static intFFI::memcmp + stringFFI\CDataptr1 + stringFFI\CDataptr2 + intsize + + + Compares size bytes from the memory areas ptr1 and + ptr2. Both ptr1 and ptr2 + can be any native data structures (FFI\CData) or PHP + strings. + + + + + &reftitle.parameters; + + + ptr1 + + + The start of one memory area. + + + + + ptr2 + + + The start of another memory area. + + + + + size + + + The number of bytes to compare. + + + + + + + + &reftitle.returnvalues; + + Returns a value less than 0 if the contents of the memory area starting at ptr1 + are considered less than the contents of the memory area starting at ptr2, + a value greater than 0 if the contents of the first memory area are considered greater than the second, + and 0 if they are equal. + + + + + diff --git a/reference/ffi/ffi/memcpy.xml b/reference/ffi/ffi/memcpy.xml new file mode 100644 index 0000000000..ed2b41948f --- /dev/null +++ b/reference/ffi/ffi/memcpy.xml @@ -0,0 +1,82 @@ + + + + + + + FFI::memcpy + Copies one memory area to another + + + + &reftitle.description; + + public static voidFFI::memcpy + FFI\CDatato + FFI\CDatastringfrom + intsize + + + Copies size bytes from the memory area from + to the memory area to. + + + + + &reftitle.parameters; + + + to + + + The start of the memory area to copy to. + + + + + from + + + The start of the memory area to copy from. + + + + + size + + + The number of bytes to copy. + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/memset.xml b/reference/ffi/ffi/memset.xml new file mode 100644 index 0000000000..447171056e --- /dev/null +++ b/reference/ffi/ffi/memset.xml @@ -0,0 +1,82 @@ + + + + + + + FFI::memset + Fills a memory area + + + + &reftitle.description; + + public static voidFFI::memset + FFI\CDataptr + intvalue + intsize + + + Fills size bytes of the memory area pointed to by + ptr with the given byte value. + + + + + &reftitle.parameters; + + + ptr + + + The start of the memory area to fill. + + + + + value + + + The byte to fill with. + + + + + size + + + The number of bytes to fill. + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/ffi/ffi/new.xml b/reference/ffi/ffi/new.xml new file mode 100644 index 0000000000..b5bdb33faa --- /dev/null +++ b/reference/ffi/ffi/new.xml @@ -0,0 +1,113 @@ + + + + + + + FFI::new + Creates a C data structure + + + + &reftitle.description; + + public FFI\CDatanullFFI::new + FFI\CTypestringtype + boolowned&true; + boolpersistent&false; + + + Creates a native data structure of the given C type. + Any type declared for the instance is allowed. + + + + + &reftitle.parameters; + + + type + + + type is a valid C declaration as string, or an + instance of FFI\CType which has already been created. + + + + + owned + + + Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together + with the returned FFI\CData object, and is released when the + last reference to that object is released by regular PHP reference counting or GC. + Unmanaged data should be released by calling FFI::free, + when no longer needed. + + + + + persistent + + + Whether to allocate the C data structure permanently on the system heap (using + malloc), or on the PHP request heap (using emalloc). + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI\CData object, + or &null; on failure. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + Calling FFI::new statically is now deprecated. + + + + + + + + + + diff --git a/reference/ffi/ffi/scope.xml b/reference/ffi/ffi/scope.xml new file mode 100644 index 0000000000..4e2118b841 --- /dev/null +++ b/reference/ffi/ffi/scope.xml @@ -0,0 +1,76 @@ + + + + + + + FFI::scope + Instantiates an FFI object with C declarations parsed during preloading + + + + &reftitle.description; + + public static FFIFFI::scope + stringname + + + Instantiates an FFI object with C declarations parsed during preloading. + + + The FFI::scope method is safe to call multiple times for the same scope. Multiple references to the + same scope may be loaded at the same time. + + + + + &reftitle.parameters; + + + name + + + The scope name defined by a special FFI_SCOPE define. + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI object. + + + + + &reftitle.seealso; + + + FFI::load + + + + + + diff --git a/reference/ffi/ffi/sizeof.xml b/reference/ffi/ffi/sizeof.xml new file mode 100644 index 0000000000..886edaf3b3 --- /dev/null +++ b/reference/ffi/ffi/sizeof.xml @@ -0,0 +1,64 @@ + + + + + + + FFI::sizeof + Gets the size of C data or types + + + + &reftitle.description; + + public static intFFI::sizeof + FFI\CDataFFI\CTypeptr + + + Returns the size of the given FFI\CData or + FFI\CType object. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the C data or type. + + + + + + + + &reftitle.returnvalues; + + The size of the memory area pointed at by ptr. + + + + + diff --git a/reference/ffi/ffi/string.xml b/reference/ffi/ffi/string.xml new file mode 100644 index 0000000000..05c785a927 --- /dev/null +++ b/reference/ffi/ffi/string.xml @@ -0,0 +1,98 @@ + + + + + + + FFI::string + Creates a PHP string from a memory area + + + + &reftitle.description; + + public static stringFFI::string + FFI\CDataptr + intnullsize&null; + + + Creates a PHP string from size bytes of the memory area + pointed to by ptr. + + + + + &reftitle.parameters; + + + ptr + + + The start of the memory area from which to create a string. + + + + + size + + + The number of bytes to copy to the string. + If size is omitted or &null;, ptr must be a zero terminated + array of C char. + + + + + + + + &reftitle.returnvalues; + + The freshly created PHP string. + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.0.0 + + size is nullable now; previously, its default was + 0. + + + + + + + + + diff --git a/reference/ffi/ffi/type.xml b/reference/ffi/ffi/type.xml new file mode 100644 index 0000000000..6d2fca9eaf --- /dev/null +++ b/reference/ffi/ffi/type.xml @@ -0,0 +1,90 @@ + + + + + + + FFI::type + Creates an FFI\CType object from a C declaration + + + + &reftitle.description; + + public FFI\CTypenullFFI::type + stringtype + + + This function creates and returns a FFI\CType object for the + given string containing a C type declaration. + Any type declared for the instance is allowed. + + + + + &reftitle.parameters; + + + type + + + A valid C declaration as string. + + + + + + + + &reftitle.returnvalues; + + Returns the freshly created FFI\CType object, + or &null; on failure. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + Calling FFI::type statically is now deprecated. + + + + + + + + + + diff --git a/reference/ffi/ffi/typeof.xml b/reference/ffi/ffi/typeof.xml new file mode 100644 index 0000000000..fd1ff65664 --- /dev/null +++ b/reference/ffi/ffi/typeof.xml @@ -0,0 +1,65 @@ + + + + + + + FFI::typeof + Gets the FFI\CType of FFI\CData + + + + &reftitle.description; + + public static FFI\CTypeFFI::typeof + FFI\CDataptr + + + Gets the FFI\CType object representing the type of the given + FFI\CData object. + + + + + &reftitle.parameters; + + + ptr + + + The handle of the pointer to a C data structure. + + + + + + + + &reftitle.returnvalues; + + Returns the FFI\CType object representing the type of the given + FFI\CData object. + + + + + diff --git a/reference/ffi/setup.xml b/reference/ffi/setup.xml new file mode 100644 index 0000000000..0cbae67c74 --- /dev/null +++ b/reference/ffi/setup.xml @@ -0,0 +1,116 @@ + + + + + + &reftitle.setup; + +
+ &reftitle.required; + + This extension requires the libffi library + to be installed. + +
+ + + &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 + + + + Allows enabling ("true") or disabling + ("false") FFI API usage, or restricting it only to + the CLI SAPI and preloaded files ("preload"). + + + The FFI API restrictions only affect the FFI class, + but not overloaded functions of FFI\CData objects. + This means that it is possible to create some FFI\CData + objects in preloaded files, and then to use these directly in PHP scripts. + + + + + + ffi.preload + string + + + + Allows preloading of FFI bindings during startup, which is not possible with FFI::load + if opcache.preload_user is set. + This directive accepts a DIRECTORY_SEPARATOR delimited list of filenames. + The preloaded bindings can be accessed by calling FFI::scope. + + + + + +
+ + + + From 33c75a19ca70b97c73fbb30fd65599934f81b118 Mon Sep 17 00:00:00 2001 From: nsfisis Date: Thu, 6 Nov 2025 04:28:05 +0900 Subject: [PATCH 2/2] =?UTF-8?q?FFI=20=E6=8B=A1=E5=BC=B5=E3=82=92=E6=96=B0?= =?UTF-8?q?=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reference/ffi/book.xml | 37 +++++---- reference/ffi/configure.xml | 11 +-- reference/ffi/ctype/getalignment.xml | 4 +- reference/ffi/ctype/getarrayelementtype.xml | 4 +- reference/ffi/ctype/getarraylength.xml | 4 +- reference/ffi/ctype/getattributes.xml | 4 +- reference/ffi/ctype/getenumkind.xml | 4 +- reference/ffi/ctype/getfuncabi.xml | 4 +- reference/ffi/ctype/getfuncparametercount.xml | 10 +-- reference/ffi/ctype/getfuncparametertype.xml | 16 ++-- reference/ffi/ctype/getfuncreturntype.xml | 4 +- reference/ffi/ctype/getkind.xml | 4 +- reference/ffi/ctype/getname.xml | 4 +- reference/ffi/ctype/getpointertype.xml | 4 +- reference/ffi/ctype/getsize.xml | 4 +- reference/ffi/ctype/getstructfieldnames.xml | 4 +- reference/ffi/ctype/getstructfieldoffset.xml | 4 +- reference/ffi/ctype/getstructfieldtype.xml | 4 +- reference/ffi/examples.xml | 76 +++++++++---------- reference/ffi/ffi.cdata.xml | 48 ++++++------ reference/ffi/ffi.ctype.xml | 4 +- reference/ffi/ffi.exception.xml | 4 +- reference/ffi/ffi.parserexception.xml | 4 +- reference/ffi/ffi.xml | 36 ++++----- reference/ffi/ffi/addr.xml | 15 ++-- reference/ffi/ffi/alignof.xml | 14 ++-- reference/ffi/ffi/arraytype.xml | 17 ++--- reference/ffi/ffi/cast.xml | 26 +++---- reference/ffi/ffi/cdef.xml | 34 ++++----- reference/ffi/ffi/free.xml | 8 +- reference/ffi/ffi/isnull.xml | 10 +-- reference/ffi/ffi/load.xml | 45 ++++++----- reference/ffi/ffi/memcmp.xml | 29 +++---- reference/ffi/ffi/memcpy.xml | 14 ++-- reference/ffi/ffi/memset.xml | 14 ++-- reference/ffi/ffi/new.xml | 31 ++++---- reference/ffi/ffi/scope.xml | 14 ++-- reference/ffi/ffi/sizeof.xml | 12 +-- reference/ffi/ffi/string.xml | 22 +++--- reference/ffi/ffi/type.xml | 19 ++--- reference/ffi/ffi/typeof.xml | 14 ++-- reference/ffi/setup.xml | 30 ++++---- 42 files changed, 340 insertions(+), 330 deletions(-) diff --git a/reference/ffi/book.xml b/reference/ffi/book.xml index 25d7502401..d554704f3f 100644 --- a/reference/ffi/book.xml +++ b/reference/ffi/book.xml @@ -1,43 +1,42 @@ - + - Foreign Function Interface + 外部関数インターフェース FFI &reftitle.intro; - This extension allows the loading of shared libraries (.DLL or - .so), calling of C functions and accessing of C data structures - in pure PHP, without having to have deep knowledge of the Zend extension API, and - without having to learn a third “intermediate” language. - The public API is implemented as a single class FFI with - several static methods (some of them may be called dynamically), and overloaded object - methods, which perform the actual interaction with C data. + この拡張は、Zend 拡張 API の深い知識が無くとも、あるいは第三の中間言語を学ぶことをせずとも、 + 純粋な PHP で共有ライブラリ (.DLL または .so) + を読み込んだり、C の関数を呼び出したり、C のデータ構造にアクセスしたりすることを + 可能とします。 + 公開 API は単一のクラス FFI として実装されています。 + このクラスの static メソッド (そのうちのいくつかは非 static メソッドとしても呼び出せます) や + オーバーロードされたオブジェクトメソッドが、実際の C のデータとのやり取りを行います。 - FFI is dangerous, since it allows to interface with the system on a very low level. - The FFI extension should only be used by developers having a working knowledge of C - and the used C APIs. To minimize the risk, the FFI API usage may be restricted - with the ffi.enable &php.ini; directive. + FFI は、システムと低レベルでやり取りできるため危険です。 + FFI 拡張は、C 言語および使用する C API についての実用的な知識を持つ開発者のみが + 用いるべきです。リスクを最小化するため、FFI API の使用は + ffi.enable &php.ini; ディレクティブによって制限できます。 - The FFI extension does not render the classic PHP extension API obsolete; it is merely - provided for ad-hoc interfacing with C functions and data structures. + FFI 拡張は、古くからある PHP 拡張の API を廃止しようとしているわけではなく、 + C の関数やデータ構造へのアドホックなインターフェースを提供するにすぎません。 - Currently, accessing FFI data structures is significantly (about 2 times) slower - than accessing native PHP arrays and objects. Therefore, it makes no sense to use - the FFI extension for speed; however, it may make sense to use it to reduce memory - consumption. + 今のところ、FFI のデータ構造へのアクセスは、ネイティブな PHP の配列やオブジェクトへのアクセスと比べて + 非常に (約 2 倍) 低速です。したがって、速度のために FFI 拡張を使うことには意味がありません。 + しかし、メモリ消費を減らすために使うのは意味があるかもしれません。 diff --git a/reference/ffi/configure.xml b/reference/ffi/configure.xml index 9d0da42da9..3e4633bf76 100644 --- a/reference/ffi/configure.xml +++ b/reference/ffi/configure.xml @@ -1,18 +1,19 @@ - +
&reftitle.install; - To enable the FFI extension, PHP has to be configured with - . + FFI 拡張を有効にするには、 + を付けて + PHP をビルドする必要があります。 - Windows users have to include php_ffi.dll into &php.ini; - to enable the FFI extension. + Windows ユーザーが FFI 拡張を有効にするには、 + &php.ini; に php_ffi.dll を含める必要があります。
diff --git a/reference/ffi/ctype/getalignment.xml b/reference/ffi/ctype/getalignment.xml index e139ba8c30..d3dbfcb057 100644 --- a/reference/ffi/ctype/getalignment.xml +++ b/reference/ffi/ctype/getalignment.xml @@ -1,11 +1,11 @@ - + FFI\CType::getAlignment - Description + 説明 diff --git a/reference/ffi/ctype/getarrayelementtype.xml b/reference/ffi/ctype/getarrayelementtype.xml index da69aa13b2..fd691c14e7 100644 --- a/reference/ffi/ctype/getarrayelementtype.xml +++ b/reference/ffi/ctype/getarrayelementtype.xml @@ -1,11 +1,11 @@ - + FFI\CType::getArrayElementType - Description + 説明 diff --git a/reference/ffi/ctype/getarraylength.xml b/reference/ffi/ctype/getarraylength.xml index d953f0bdec..7b1f455a74 100644 --- a/reference/ffi/ctype/getarraylength.xml +++ b/reference/ffi/ctype/getarraylength.xml @@ -1,11 +1,11 @@ - + FFI\CType::getArrayLength - Description + 説明 diff --git a/reference/ffi/ctype/getattributes.xml b/reference/ffi/ctype/getattributes.xml index d18a2ef434..0b6cf93d6e 100644 --- a/reference/ffi/ctype/getattributes.xml +++ b/reference/ffi/ctype/getattributes.xml @@ -1,11 +1,11 @@ - + FFI\CType::getAttributes - Description + 説明 diff --git a/reference/ffi/ctype/getenumkind.xml b/reference/ffi/ctype/getenumkind.xml index 3b8d53b23d..8bab3fb409 100644 --- a/reference/ffi/ctype/getenumkind.xml +++ b/reference/ffi/ctype/getenumkind.xml @@ -1,11 +1,11 @@ - + FFI\CType::getEnumKind - Description + 説明 diff --git a/reference/ffi/ctype/getfuncabi.xml b/reference/ffi/ctype/getfuncabi.xml index 138a3268e2..06d83d082a 100644 --- a/reference/ffi/ctype/getfuncabi.xml +++ b/reference/ffi/ctype/getfuncabi.xml @@ -1,11 +1,11 @@ - + FFI\CType::getFuncABI - Description + 説明 diff --git a/reference/ffi/ctype/getfuncparametercount.xml b/reference/ffi/ctype/getfuncparametercount.xml index 8618fb6e9b..00a14d8fa4 100644 --- a/reference/ffi/ctype/getfuncparametercount.xml +++ b/reference/ffi/ctype/getfuncparametercount.xml @@ -1,11 +1,11 @@ - + FFI\CType::getFuncParameterCount - Retrieve the count of parameters of a function type + 関数型の引数の数を取得する @@ -28,9 +28,9 @@ &reftitle.returnvalues; - Returns the number of parameters for the underlying function type. - If the underlying type is not a function, an - FFI\Exception is thrown. + 内部的に保持している関数型の引数の数を返します。 + 内部的に保持している型が関数でない場合、 + FFI\Exception をスローします。 diff --git a/reference/ffi/ctype/getfuncparametertype.xml b/reference/ffi/ctype/getfuncparametertype.xml index 973e081eac..5cc756172e 100644 --- a/reference/ffi/ctype/getfuncparametertype.xml +++ b/reference/ffi/ctype/getfuncparametertype.xml @@ -1,11 +1,11 @@ - + FFI\CType::getFuncParameterType - Retrieve the type of a function parameter + 関数の引数の型を取得する @@ -15,7 +15,7 @@ intindex - Returns the type of a parameter for the underlying function type. + 内部的に保持している関数型の引数の型を返します。 @@ -27,7 +27,7 @@ index - Index of the function parameter, zero-based. + 関数の引数の添字 (ゼロ始まり)。 @@ -37,10 +37,10 @@ &reftitle.returnvalues; - Returns the type of a parameter for the underlying function type. - If the underlying type is not a function, or the given index is outside - of the range of parameters of the function, an - FFI\Exception is thrown. + 内部的に保持している関数型の引数の型を返します。 + 内部的に保持している型が関数でない場合や、 + 与えられた添字がその関数の引数の範囲外の場合、 + FFI\Exception をスローします。 diff --git a/reference/ffi/ctype/getfuncreturntype.xml b/reference/ffi/ctype/getfuncreturntype.xml index ab89eb4df2..a04d715592 100644 --- a/reference/ffi/ctype/getfuncreturntype.xml +++ b/reference/ffi/ctype/getfuncreturntype.xml @@ -1,11 +1,11 @@ - + FFI\CType::getFuncReturnType - Description + 説明 diff --git a/reference/ffi/ctype/getkind.xml b/reference/ffi/ctype/getkind.xml index 479586f17e..e91cbe308e 100644 --- a/reference/ffi/ctype/getkind.xml +++ b/reference/ffi/ctype/getkind.xml @@ -1,11 +1,11 @@ - + FFI\CType::getKind - Description + 説明 diff --git a/reference/ffi/ctype/getname.xml b/reference/ffi/ctype/getname.xml index f1e1cca175..803191df48 100644 --- a/reference/ffi/ctype/getname.xml +++ b/reference/ffi/ctype/getname.xml @@ -1,11 +1,11 @@ - + FFI\CType::getName - Description + 説明 diff --git a/reference/ffi/ctype/getpointertype.xml b/reference/ffi/ctype/getpointertype.xml index cb511fa048..928e942c98 100644 --- a/reference/ffi/ctype/getpointertype.xml +++ b/reference/ffi/ctype/getpointertype.xml @@ -1,11 +1,11 @@ - + FFI\CType::getPointerType - Description + 説明 diff --git a/reference/ffi/ctype/getsize.xml b/reference/ffi/ctype/getsize.xml index 70fa540e0a..da92c3fd31 100644 --- a/reference/ffi/ctype/getsize.xml +++ b/reference/ffi/ctype/getsize.xml @@ -1,11 +1,11 @@ - + FFI\CType::getSize - Description + 説明 diff --git a/reference/ffi/ctype/getstructfieldnames.xml b/reference/ffi/ctype/getstructfieldnames.xml index 04597bf021..324b727954 100644 --- a/reference/ffi/ctype/getstructfieldnames.xml +++ b/reference/ffi/ctype/getstructfieldnames.xml @@ -1,11 +1,11 @@ - + FFI\CType::getStructFieldNames - Description + 説明 diff --git a/reference/ffi/ctype/getstructfieldoffset.xml b/reference/ffi/ctype/getstructfieldoffset.xml index febea29ba3..b841966592 100644 --- a/reference/ffi/ctype/getstructfieldoffset.xml +++ b/reference/ffi/ctype/getstructfieldoffset.xml @@ -1,11 +1,11 @@ - + FFI\CType::getStructFieldOffset - Description + 説明 diff --git a/reference/ffi/ctype/getstructfieldtype.xml b/reference/ffi/ctype/getstructfieldtype.xml index 9a2d0cc3cd..c9e0292e25 100644 --- a/reference/ffi/ctype/getstructfieldtype.xml +++ b/reference/ffi/ctype/getstructfieldtype.xml @@ -1,11 +1,11 @@ - + FFI\CType::getStructFieldType - Description + 説明 diff --git a/reference/ffi/examples.xml b/reference/ffi/examples.xml index eedebfb82d..17aa3261ed 100644 --- a/reference/ffi/examples.xml +++ b/reference/ffi/examples.xml @@ -1,32 +1,32 @@ - + &reftitle.examples;
- Basic FFI usage + FFI の基本的な使い方 - Before diving into the details of the FFI API, lets take a look at a few examples - demonstrating the simplicity of the FFI API usage for regular tasks. + FFI API の詳細に深く立ち入る前に、よくあるタスクに対する FFI API の使い方が + どれほど簡単かを示す例をいくつか見てみましょう。 - Some of these examples require libc.so.6 and as such will - not work on systems where it is not available. + これらの例の中には、libc.so.6 を必要とするものがあります。 + それらは、このライブラリが利用できないシステムでは動きません。 - Calling a function from shared library + 共有ライブラリの関数を呼ぶ printf("Hello %s!\n", "world"); ?> ]]> @@ -41,17 +41,17 @@ Hello world! - Note that some C functions need specific calling conventions, e.g. __fastcall, - __stdcall or ,__vectorcall. + C の関数のうちのいくつかは、特定の呼び出し規約 (例: __fastcall、 + __stdcall、,__vectorcall など) を必要とすることに注意してください。 - Calling a function, returning a structure through an argument + 関数を呼び出し、構造体を引数経由で返す new("struct timeval"); $tz = $ffi->new("struct timezone"); -// call C's gettimeofday() +// C の gettimeofday() を呼ぶ var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz))); -// access field of C data structure +// C のデータ構造のフィールドにアクセスする var_dump($tv->tv_sec); -// print the whole C data structure +// C のデータ構造全体を出力する var_dump($tz); ?> ]]> @@ -97,15 +97,15 @@ object(FFI\CData:struct timezone)#3 (2) { - Accessing existing C variables + 既存の C の変数にアクセスする errno); ?> ]]> @@ -120,19 +120,19 @@ int(0) - Creating and Modifying C variables + C の変数を作成して書き換える cdata); -// simple assignment +// 単純な代入 $x->cdata = 5; var_dump($x->cdata); -// compound assignment +// 複合代入 $x->cdata += 2; var_dump($x->cdata); ?> @@ -150,13 +150,13 @@ int(7) - Working with C arrays + C の配列を扱う - Working with C enums + C の enum を扱う
- PHP Callbacks + PHP のコールバック - It is possible to assign a PHP closure to a native variable of function pointer type - or to pass it as a function argument: + PHP のクロージャを、関数ポインタ型のネイティブ変数に代入したり、 + 関数の引数として渡したりできます。 - Assigning a PHP <classname>Closure</classname> to a C function pointer + PHP の <classname>Closure</classname> を C の関数ポインタに代入する - Although this works, this functionality is not supported on all libffi platforms, is not efficient - and leaks resources by the end of request. + これは動作こそしますが、この機能は libffi が動作するすべてのプラットフォームでサポートされているわけではありません。 + また、非効率的であり、リクエストの終了時にリソースがリークします。 - It is therefore recommended to minimize the usage of PHP callbacks. + したがって、PHP のコールバックの使用は最小限にすることを推奨します。
- A Complete PHP/FFI/preloading Example + PHP/FFI/事前ロードの完全な例 php.ini diff --git a/reference/ffi/ffi.cdata.xml b/reference/ffi/ffi.cdata.xml index 237d7d2edb..a252cc5217 100644 --- a/reference/ffi/ffi.cdata.xml +++ b/reference/ffi/ffi.cdata.xml @@ -1,10 +1,10 @@ - + - C Data Handles + C のデータハンドル FFI\CData @@ -13,87 +13,87 @@
&reftitle.intro; - FFI\CData objects can be used in a number of ways as a regular + FFI\CData オブジェクトは、通常の PHP データのように様々な方法で使用できます: - PHP data: - C data of scalar types can be read and assigned via the $cdata property, e.g. + スカラー型の C のデータは $cdata プロパティを通してアクセスできます。例: $x = FFI::new('int'); $x->cdata = 42; - C struct and union fields can be accessed as regular PHP object property, e.g. + C の構造体や共用体のフィールドは通常の PHP のオブジェクトプロパティのようにアクセスできます。例: $cdata->field - C array elements can be accessed as regular PHP array elements, e.g. + C の配列要素は通常の PHP の配列要素のようにアクセスできます。例: $cdata[$offset] - C arrays can be iterated using &foreach; statements. + C の配列は &foreach; 文を使って反復できます。 - C arrays can be used as arguments of count. + C の配列は count の引数として使えます。 - C pointers can be dereferenced as arrays, e.g. $cdata[0] + C のポインタは配列のように参照外しできます。例: $cdata[0] - C pointers can be compared using regular comparison operators (<, - <=, ==, !=, >=, >). + C のポインタは通常の比較演算子を使って比較できます (<、 + <=、==、!=、>=、>)。 - C pointers can be incremented and decremented using regular +/-/ - ++/-- operations, e.g. $cdata += 5 + C のポインタは通常の +/-/ + ++/-- 演算子を使ってインクリメント・デクリメントできます。例: $cdata += 5 - C pointers can be subtracted from another using regular - operations. + C のポインタは通常の - 演算子を使って他のポインタと引き算できます。 - C pointers to functions can be called as a regular PHP closure, e.g. $cdata() + C の関数ポインタは通常の PHP のクロージャのように呼び出せます。例: $cdata() - Any C data can be duplicated using the clone - operator, e.g. $cdata2 = clone $cdata; + 任意の C のデータは clone 演算子を使って + 複製できます。例: $cdata2 = clone $cdata; - Any C data can be visualized using var_dump, print_r, etc. + 任意の C のデータは var_dump や print_r 等を + 使って可視化できます。 - FFI\CData can now be assigned to structs and fields as of PHP 8.3.0. + PHP 8.3.0 以降、FFI\CData は構造体やフィールドに代入できるようになりました。 - Notable limitations are that FFI\CData instances do not support - isset, empty and unset, - and that wrapped C structs and unions do not implement Traversable. + 特筆すべき制限として、FFI\CData インスタンスは + isset、empty、unset をサポートしていません。 + また、ラップされた C の構造体や共用体は Traversable を実装していません。 @@ -128,7 +128,7 @@ 8.3.0 - FFI\CData can now be assigned to structs and fields. + FFI\CData は構造体やフィールドに代入できるようになりました。 diff --git a/reference/ffi/ffi.ctype.xml b/reference/ffi/ffi.ctype.xml index d3d66049a5..9b08167fe9 100644 --- a/reference/ffi/ffi.ctype.xml +++ b/reference/ffi/ffi.ctype.xml @@ -1,10 +1,10 @@ - + - C Type Handles + C の型ハンドル FFI\CType diff --git a/reference/ffi/ffi.exception.xml b/reference/ffi/ffi.exception.xml index a6db36a1e1..d34b11321a 100644 --- a/reference/ffi/ffi.exception.xml +++ b/reference/ffi/ffi.exception.xml @@ -1,10 +1,10 @@ - + - FFI Exceptions + FFI 例外 FFI\Exception diff --git a/reference/ffi/ffi.parserexception.xml b/reference/ffi/ffi.parserexception.xml index a9e49a0308..598a9503ec 100644 --- a/reference/ffi/ffi.parserexception.xml +++ b/reference/ffi/ffi.parserexception.xml @@ -1,10 +1,10 @@ - + - FFI Parser Exceptions + FFI パーサー例外 FFI\ParserException diff --git a/reference/ffi/ffi.xml b/reference/ffi/ffi.xml index 6f295c38c9..6fbc6e8064 100644 --- a/reference/ffi/ffi.xml +++ b/reference/ffi/ffi.xml @@ -1,10 +1,10 @@ - + - Main interface to C code and data + C のコードやデータへの主要インターフェース FFI @@ -13,25 +13,27 @@
&reftitle.intro; - Objects of this class are created by the factory methods FFI::cdef, - FFI::load or FFI::scope. Defined C variables - are made available as properties of the FFI instance, and defined C functions are made available - as methods of the FFI instance. Declared C types can be used to create new C data structures - using FFI::new and FFI::type. + このクラスのオブジェクトは、ファクトリーメソッドである FFI::cdef や + FFI::load、FFI::scope によって作成されます。 + 定義された C の変数は FFI インスタンスのプロパティとして利用可能となり、 + 定義された C の関数は FFI インスタンスのメソッドとして利用可能となります。 + 宣言された C の型は、FFI::new や FFI::type を使って + 新しい C のデータ構造を作成するのに使用できます。 - FFI definition parsing and shared library loading may take significant time. It is not useful - to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions - and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files - may be extended with special FFI_SCOPE defines (e.g. #define FFI_SCOPE "foo"; - the default scope is "C") and then loaded by FFI::load during preloading. - This leads to the creation of a persistent binding, that will be available to all the following - requests through FFI::scope. - Refer to the complete PHP/FFI/preloading example - for details. + FFI 定義のパースや共有ライブラリの読み込みには長い時間がかかることがあります。 + Web 環境において、各 HTTP リクエストでこれを行うのは不便です。 + しかし、FFI 定義やライブラリを PHP の起動時に事前ロードし、FFI オブジェクトを必要なときにインスタンス化することが可能です。 + ヘッダーファイルは特殊な define である FFI_SCOPE によって拡張することができ + (例: #define FFI_SCOPE "foo"。デフォルトのスコープは "C" です)、 + 事前ロード中に FFI::load によって読み込むことができます。 + これによって、永続的なバインディングが作成されます。 + こうして作られたバインディングは、FFI::scope を通じて後続する全リクエストで利用可能となります。 + 詳しくは PHP/FFI/事前ロードの完全な例 + を参照してください。 - It is possible to preload more than one C header file into the same scope. + 複数の C のヘッダーファイルを同一のスコープへと事前ロードできます。
diff --git a/reference/ffi/ffi/addr.xml b/reference/ffi/ffi/addr.xml index bcb09b7e41..e9bb00eb90 100644 --- a/reference/ffi/ffi/addr.xml +++ b/reference/ffi/ffi/addr.xml @@ -1,11 +1,11 @@ - + FFI::addr - Creates an unmanaged pointer to C data + C のデータへのアンマネージドなポインターを作成する @@ -15,9 +15,10 @@ FFI\CDataptr - Creates an unmanaged pointer to the C data represented by the given - FFI\CData. The source ptr must survive the - resulting pointer. This function is mainly useful to pass arguments to C functions by pointer. + 与えられた FFI\CData によって表される C のデータへの + アンマネージドなポインターを作成します。元になる ptr + は返されるポインターよりも長く生存しなければなりません。 + この関数は、主に C の関数へ引数をポインタ経由で渡すのに便利です。 @@ -28,7 +29,7 @@ ptr - The handle of the pointer to a C data structure. + C のデータ構造へのポインターのハンドル。 @@ -38,7 +39,7 @@ &reftitle.returnvalues; - Returns the freshly created FFI\CData object. + 新しく作成された FFI\CData オブジェクトを返します。 diff --git a/reference/ffi/ffi/alignof.xml b/reference/ffi/ffi/alignof.xml index 325883abf1..c459db90e9 100644 --- a/reference/ffi/ffi/alignof.xml +++ b/reference/ffi/ffi/alignof.xml @@ -1,11 +1,11 @@ - + FFI::alignof - Gets the alignment + アラインメントを取得する @@ -15,8 +15,8 @@ FFI\CDataFFI\CTypeptr - Gets the alignment of the given FFI\CData or - FFI\CType object. + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのアラインメントを返します。 @@ -27,7 +27,7 @@ ptr - The handle of the C data or type. + C のデータまたは C の型のハンドル。 @@ -37,8 +37,8 @@ &reftitle.returnvalues; - Returns the alignment of the given FFI\CData or - FFI\CType object. + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのアラインメントを返します。 diff --git a/reference/ffi/ffi/arraytype.xml b/reference/ffi/ffi/arraytype.xml index ed0807fb7e..660e1009da 100644 --- a/reference/ffi/ffi/arraytype.xml +++ b/reference/ffi/ffi/arraytype.xml @@ -1,11 +1,11 @@ - + FFI::arrayType - Dynamically constructs a new C array type + 新しい C の配列型を動的に構築する @@ -16,9 +16,9 @@ arraydimensions - Dynamically constructs a new C array type with elements of type defined by type, - and dimensions specified by dimensions. In the following example $t1 - and $t2 are equivalent array types: + type で指定された要素型と dimensions で指定された次元を持つ + 新しい C の配列型を動的に構築します。以下の例において $t1 と + $t2 は等しい配列型です。 type - A valid C declaration as string, or an instance of FFI\CType - which has already been created. + 有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。 @@ -48,7 +47,7 @@ $t2 = FFI::arrayType(FFI::type("int"), [2, 3]); dimensions - The dimensions of the type as array. + 型の次元を表す array。 @@ -58,7 +57,7 @@ $t2 = FFI::arrayType(FFI::type("int"), [2, 3]); &reftitle.returnvalues; - Returns the freshly created FFI\CType object. + 新しく作成した FFI\CType オブジェクトを返します。 diff --git a/reference/ffi/ffi/cast.xml b/reference/ffi/ffi/cast.xml index 107fac3fd9..eebafa64f2 100644 --- a/reference/ffi/ffi/cast.xml +++ b/reference/ffi/ffi/cast.xml @@ -1,11 +1,11 @@ - + FFI::cast - Performs a C type cast + C の型キャストを実行する @@ -16,12 +16,13 @@ FFI\CDataintfloatboolnullptr - FFI::cast creates a new FFI\CData - object, that references the same C data structure, but is associated with a different type. - The resulting object does not own the C data, and the source ptr - must survive the result. The C type may be specified as a string with any - valid C type declaration or as FFI\CType object, created before. - Any type declared for the instance is allowed. + FFI::cast は、同じ C のデータ構造を参照するものの別の型が紐付けられた + FFI\CData オブジェクトを新しく作成します。 + 返却されるオブジェクトはその C のデータを所有しません。元の ptr は + その返り値よりも長く生存する必要があります。 + C の型は、有効な C の型宣言を表す string として指定するか、 + 以前作成した FFI\CType オブジェクトとして指定します。 + このインスタンスで宣言された任意の型が使えます。 @@ -32,8 +33,7 @@ type - A valid C declaration as string, or an instance of FFI\CType - which has already been created. + 有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。 @@ -41,7 +41,7 @@ ptr - The handle of the pointer to a C data structure. + C のデータ構造へのポインターのハンドル。 @@ -51,7 +51,7 @@ &reftitle.returnvalues; - Returns the freshly created FFI\CData object. + 新しく作成された FFI\CData オブジェクトを返します。 @@ -70,7 +70,7 @@ 8.3.0 - Calling FFI::cast statically is now deprecated. + FFI::cast を static メソッドとして呼び出すのは非推奨となりました。 diff --git a/reference/ffi/ffi/cdef.xml b/reference/ffi/ffi/cdef.xml index 3305dd2ccc..454ce772eb 100644 --- a/reference/ffi/ffi/cdef.xml +++ b/reference/ffi/ffi/cdef.xml @@ -1,11 +1,11 @@ - + FFI::cdef - Creates a new FFI object + 新しい FFI オブジェクトを作成する @@ -16,7 +16,7 @@ stringnulllib&null; - Creates a new FFI object. + 新しい FFI オブジェクトを作成します。 @@ -27,14 +27,13 @@ code - A string containing a sequence of declarations in regular C language - (types, structures, functions, variables, etc). Actually, this string may - be copy-pasted from C header files. + 通常の C 言語の宣言 (型、構造体、関数、変数など) を含む文字列。 + 実際には、この文字列は C のヘッダーファイルからコピーペーストしてきたものかもしれません。 - C preprocessor directives are not supported, i.e. #include, - #define and CPP macros do not work. + C のプリプロセッサーディレクティブはサポートされていません。 + 例えば、#include や #define、プリプロセッサーマクロは動作しません。 @@ -43,14 +42,15 @@ lib - The name of a shared library file, to be loaded and linked with the - definitions. + 共有ライブラリの名前。 + ここで指定したライブラリが読み込まれ、与えた定義とリンクされます。 - If lib is omitted or &null;, platforms supporting RTLD_DEFAULT - attempt to lookup symbols declared in code in the normal global - scope. Other systems will fail to resolve these symbols. + lib を省略したり &null; を渡したりすると、 + RTLD_DEFAULT をサポートしているプラットフォームでは、 + 通常のグローバルスコープから code で宣言されているシンボルを探索しようとします。 + そうでないシステムでは、シンボルの解決に失敗します。 @@ -61,7 +61,7 @@ &reftitle.returnvalues; - Returns the freshly created FFI object. + 新しく作成された FFI オブジェクトを返します。 @@ -79,14 +79,14 @@ 8.3.0 - C functions returning void return a PHP null - instead of FFI\CType::TYPE_VOID. + void を返す C の関数が、FFI\CType::TYPE_VOID + ではなく PHP の null を返すようになりました。 8.0.0 - lib is nullable now. + lib は、nullable になりました。 diff --git a/reference/ffi/ffi/free.xml b/reference/ffi/ffi/free.xml index 1616761c65..f41081400e 100644 --- a/reference/ffi/ffi/free.xml +++ b/reference/ffi/ffi/free.xml @@ -1,11 +1,11 @@ - + FFI::free - Releases an unmanaged data structure + アンマネージドなデータ構造を解放する @@ -15,7 +15,7 @@ FFI\CDataptr - Manually releases a previously created unmanaged data structure. + 以前に作成されたアンマネージドなデータ構造を手で解放します。 @@ -26,7 +26,7 @@ ptr - The handle of the unmanaged pointer to a C data structure. + C のデータ構造へのアンマネージドなポインターのハンドル。 diff --git a/reference/ffi/ffi/isnull.xml b/reference/ffi/ffi/isnull.xml index 75cd4b327a..fa514d8d75 100644 --- a/reference/ffi/ffi/isnull.xml +++ b/reference/ffi/ffi/isnull.xml @@ -1,11 +1,11 @@ - + FFI::isNull - Checks whether a FFI\CData is a null pointer + FFI\CData が NULL ポインターかどうかを調べる @@ -15,7 +15,7 @@ FFI\CDataptr - Checks whether a FFI\CData is a null pointer. + FFI\CData が NULL ポインターかどうかを調べます。 @@ -26,7 +26,7 @@ ptr - The handle of the pointer to a C data structure. + C のデータ構造へのポインターのハンドル。 @@ -36,7 +36,7 @@ &reftitle.returnvalues; - Returns whether a FFI\CData is a null pointer. + FFI\CData が NULL ポインターかどうかを返します。 diff --git a/reference/ffi/ffi/load.xml b/reference/ffi/ffi/load.xml index 2359021c11..5aa07088c5 100644 --- a/reference/ffi/ffi/load.xml +++ b/reference/ffi/ffi/load.xml @@ -1,11 +1,11 @@ - + FFI::load - Loads C declarations from a C header file + C のヘッダーファイルから C の宣言を読み込む @@ -15,8 +15,9 @@ stringfilename - Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, - using special FFI_LIB defines in the loaded C header file. + C のヘッダーファイルから C の宣言を読み込みます。 + 読み込まれる C のヘッダーファイル内で特殊な define FFI_LIB を使うことで、 + 読み込む共有ライブラリを指定することが可能です。 @@ -27,24 +28,25 @@ filename - The name of a C header file. + C のヘッダーファイル名。 - C preprocessor directives are not supported, i.e. #include, - #define and CPP macros do not work, except for special cases - listed below. + C のプリプロセッサーディレクティブはサポートされていません。 + 例えば、#include や #define、プリプロセッサーマクロは動作しません。 + ただし、次に挙げる特殊な場合を除きます。 - The header file should contain a #define statement for the - FFI_SCOPE variable, e.g.: #define FFI_SCOPE "MYLIB". - Refer to the class introduction for details. + このヘッダーファイルでは、#define 文で + FFI_SCOPE 変数を定義すべきです + (例: #define FFI_SCOPE "MYLIB")。 + 詳しくは FFI クラスの概要 を参照してください。 - The header file may contain a #define statement for the - FFI_LIB variable to specify the library it exposes. If it is - a system library only the file name is required, e.g.: #define FFI_LIB - "libc.so.6". If it is a custom library, a relative path is required, - e.g.: #define FFI_LIB "./mylib.so". + このヘッダーファイルでは、#define 文で + FFI_LIB 変数を定義することで、公開するライブラリを指定しても構いません。 + それがシステムライブラリなら、必要なのはファイル名だけです (例: #define FFI_LIB + "libc.so.6")。カスタムライブラリなら、相対パスが必要です + (例: #define FFI_LIB "./mylib.so")。 @@ -54,7 +56,8 @@ &reftitle.returnvalues; - Returns the freshly created FFI object, or &null; on failure. + 新しく作成された FFI オブジェクトを返します。 + 失敗時には &null; を返します。 @@ -72,10 +75,10 @@ 8.3.0 - FFI::load is now allowed in - preload scripts when the - current system user is the same as the one defined in the - opcache.preload_user configuration directive. + 現在のシステムユーザが opcache.preload_user + 設定ディレクティブで定義されたユーザと同じである場合、 + 事前ロードスクリプト の中で + FFI::load を呼べるようになりました。 diff --git a/reference/ffi/ffi/memcmp.xml b/reference/ffi/ffi/memcmp.xml index 7e29a6b485..ebb4aa044e 100644 --- a/reference/ffi/ffi/memcmp.xml +++ b/reference/ffi/ffi/memcmp.xml @@ -1,11 +1,11 @@ - + FFI::memcmp - Compares memory areas + メモリ領域を比較する @@ -17,10 +17,11 @@ intsize - Compares size bytes from the memory areas ptr1 and - ptr2. Both ptr1 and ptr2 - can be any native data structures (FFI\CData) or PHP - strings. + メモリ領域 ptr1 と ptr2 を + size バイト分比較します。 + ptr1 も ptr2 も、 + ネイティブデータ構造 (FFI\CData) または + PHP の string にできます。 @@ -31,7 +32,7 @@ ptr1 - The start of one memory area. + 一方のメモリ領域の開始位置。 @@ -39,7 +40,7 @@ ptr2 - The start of another memory area. + もう一方のメモリ領域の開始位置。 @@ -47,7 +48,7 @@ size - The number of bytes to compare. + 比較するバイト数。 @@ -57,10 +58,12 @@ &reftitle.returnvalues; - Returns a value less than 0 if the contents of the memory area starting at ptr1 - are considered less than the contents of the memory area starting at ptr2, - a value greater than 0 if the contents of the first memory area are considered greater than the second, - and 0 if they are equal. + ptr1 から始まるメモリ領域の中身が + ptr2 から始まるメモリ領域の中身より小さければ、 + 0 より小さい値を返します。 + ptr1 が ptr2 より大きければ、 + 0 より大きい値を返します。 + 両者が等しければ 0 を返します。 diff --git a/reference/ffi/ffi/memcpy.xml b/reference/ffi/ffi/memcpy.xml index ed2b41948f..55bacdf808 100644 --- a/reference/ffi/ffi/memcpy.xml +++ b/reference/ffi/ffi/memcpy.xml @@ -1,11 +1,11 @@ - + FFI::memcpy - Copies one memory area to another + あるメモリ領域を別の領域へコピーする @@ -17,8 +17,8 @@ intsize - Copies size bytes from the memory area from - to the memory area to. + from のメモリ領域から size バイト分を + to のメモリ領域へとコピーします。 @@ -29,7 +29,7 @@ to - The start of the memory area to copy to. + コピー先のメモリ領域の開始位置。 @@ -37,7 +37,7 @@ from - The start of the memory area to copy from. + コピー元のメモリ領域の開始位置。 @@ -45,7 +45,7 @@ size - The number of bytes to copy. + コピーするバイト数。 diff --git a/reference/ffi/ffi/memset.xml b/reference/ffi/ffi/memset.xml index 447171056e..fb773b05db 100644 --- a/reference/ffi/ffi/memset.xml +++ b/reference/ffi/ffi/memset.xml @@ -1,11 +1,11 @@ - + FFI::memset - Fills a memory area + メモリ領域を埋める @@ -17,8 +17,8 @@ intsize - Fills size bytes of the memory area pointed to by - ptr with the given byte value. + ptr が指すメモリ領域を size バイト分 + 与えられた value で埋めます。 @@ -29,7 +29,7 @@ ptr - The start of the memory area to fill. + 埋めるメモリ領域の開始位置。 @@ -37,7 +37,7 @@ value - The byte to fill with. + 埋めるのに使うバイト。 @@ -45,7 +45,7 @@ size - The number of bytes to fill. + 埋めるバイト数。 diff --git a/reference/ffi/ffi/new.xml b/reference/ffi/ffi/new.xml index b5bdb33faa..c8b3169977 100644 --- a/reference/ffi/ffi/new.xml +++ b/reference/ffi/ffi/new.xml @@ -1,11 +1,11 @@ - + FFI::new - Creates a C data structure + C のデータ構造を作成する @@ -17,8 +17,8 @@ boolpersistent&false; - Creates a native data structure of the given C type. - Any type declared for the instance is allowed. + 与えられた C の型を持つネイティブデータ構造を作成します。 + このインスタンスで宣言された任意の型が使えます。 @@ -29,8 +29,8 @@ type - type is a valid C declaration as string, or an - instance of FFI\CType which has already been created. + type は、有効な C の宣言を表す string か、 + 作成済みの FFI\CType のインスタンスです。 @@ -38,11 +38,10 @@ owned - Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together - with the returned FFI\CData object, and is released when the - last reference to that object is released by regular PHP reference counting or GC. - Unmanaged data should be released by calling FFI::free, - when no longer needed. + 所有された (マネージドな) データを作成するか、アンマネージドなデータを作成するか。 + マネージドデータは返される FFI\CData オブジェクトと共に生存し、 + そのオブジェクトへの最後の参照が PHP の通常のリファレンスカウントや GC によって解放されたときに解放されます。 + アンマネージドなデータは、不要になったら FFI::free を呼んで解放すべきです。 @@ -50,8 +49,8 @@ persistent - Whether to allocate the C data structure permanently on the system heap (using - malloc), or on the PHP request heap (using emalloc). + この C のデータ構造をシステムヒープ上に永続的に確保するか (malloc を使用)、 + PHP のリクエストヒープ上に確保するか (emalloc を使用)。 @@ -61,8 +60,8 @@ &reftitle.returnvalues; - Returns the freshly created FFI\CData object, - or &null; on failure. + 新しく作成された FFI\CData オブジェクトを返します。 + 失敗時には &null; を返します。 @@ -81,7 +80,7 @@ 8.3.0 - Calling FFI::new statically is now deprecated. + FFI::new を static メソッドとして呼び出すのは非推奨となりました。 diff --git a/reference/ffi/ffi/scope.xml b/reference/ffi/ffi/scope.xml index 4e2118b841..8bc7c6308e 100644 --- a/reference/ffi/ffi/scope.xml +++ b/reference/ffi/ffi/scope.xml @@ -1,11 +1,11 @@ - + FFI::scope - Instantiates an FFI object with C declarations parsed during preloading + 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する @@ -15,11 +15,11 @@ stringname - Instantiates an FFI object with C declarations parsed during preloading. + 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化します。 - The FFI::scope method is safe to call multiple times for the same scope. Multiple references to the - same scope may be loaded at the same time. + FFI::scope メソッドを同じスコープに対して複数回呼んでも安全です。 + 同じスコープを指す複数の参照は同時に読み込まれるかもしれません。 @@ -30,7 +30,7 @@ name - The scope name defined by a special FFI_SCOPE define. + 特殊な FFI_SCOPE define によって定義されたスコープ名。 @@ -40,7 +40,7 @@ &reftitle.returnvalues; - Returns the freshly created FFI object. + 新しく作成された FFI オブジェクトを返します。 diff --git a/reference/ffi/ffi/sizeof.xml b/reference/ffi/ffi/sizeof.xml index 886edaf3b3..5dff77d9e4 100644 --- a/reference/ffi/ffi/sizeof.xml +++ b/reference/ffi/ffi/sizeof.xml @@ -1,11 +1,11 @@ - + FFI::sizeof - Gets the size of C data or types + C のデータサイズまたは C の型サイズを取得する @@ -15,8 +15,8 @@ FFI\CDataFFI\CTypeptr - Returns the size of the given FFI\CData or - FFI\CType object. + 与えられた FFI\CData オブジェクトまたは + FFI\CType オブジェクトのサイズを返します。 @@ -27,7 +27,7 @@ ptr - The handle of the C data or type. + C のデータまたは C の型のハンドル。 @@ -37,7 +37,7 @@ &reftitle.returnvalues; - The size of the memory area pointed at by ptr. + ptr が指すメモリ領域のサイズ。 diff --git a/reference/ffi/ffi/string.xml b/reference/ffi/ffi/string.xml index 05c785a927..791af9f83b 100644 --- a/reference/ffi/ffi/string.xml +++ b/reference/ffi/ffi/string.xml @@ -1,11 +1,11 @@ - + FFI::string - Creates a PHP string from a memory area + メモリ領域から PHP の文字列を作成する @@ -16,8 +16,8 @@ intnullsize&null; - Creates a PHP string from size bytes of the memory area - pointed to by ptr. + ptr が指すメモリ領域の size バイト分から + PHP の string を作成します。 @@ -28,7 +28,7 @@ ptr - The start of the memory area from which to create a string. + string を作成する元となるメモリ領域の開始位置。 @@ -36,9 +36,9 @@ size - The number of bytes to copy to the string. - If size is omitted or &null;, ptr must be a zero terminated - array of C char. + string へコピーするバイト数。 + size を省略したり &null; を指定したりする場合、 + ptr はゼロ終端された C の char 配列でなければなりません。 @@ -48,7 +48,7 @@ &reftitle.returnvalues; - The freshly created PHP string. + 新しく作成された PHP の string。 @@ -66,8 +66,8 @@ 8.0.0 - size is nullable now; previously, its default was - 0. + size が nullable になりました。以前は + 0 がデフォルトでした。 diff --git a/reference/ffi/ffi/type.xml b/reference/ffi/ffi/type.xml index 6d2fca9eaf..fa3eba2d51 100644 --- a/reference/ffi/ffi/type.xml +++ b/reference/ffi/ffi/type.xml @@ -1,11 +1,11 @@ - + FFI::type - Creates an FFI\CType object from a C declaration + C の宣言から FFI\CType オブジェクトを作成する @@ -15,9 +15,10 @@ stringtype - This function creates and returns a FFI\CType object for the - given string containing a C type declaration. - Any type declared for the instance is allowed. + この関数は、C の型宣言を持つ string を渡すと、 + 与えられた string に対応する + FFI\CType オブジェクトを作成して返します。 + このインスタンスで宣言された任意の型が使えます。 @@ -28,7 +29,7 @@ type - A valid C declaration as string. + 有効な C の宣言を持つ string。 @@ -38,8 +39,8 @@ &reftitle.returnvalues; - Returns the freshly created FFI\CType object, - or &null; on failure. + 新しく作成された FFI\CType オブジェクトを返します。 + 失敗時には &null; を返します。 @@ -58,7 +59,7 @@ 8.3.0 - Calling FFI::type statically is now deprecated. + FFI::type を static メソッドとして呼び出すのは非推奨となりました。 diff --git a/reference/ffi/ffi/typeof.xml b/reference/ffi/ffi/typeof.xml index fd1ff65664..9e03f07a85 100644 --- a/reference/ffi/ffi/typeof.xml +++ b/reference/ffi/ffi/typeof.xml @@ -1,11 +1,11 @@ - + FFI::typeof - Gets the FFI\CType of FFI\CData + FFI\CData の FFI\CType を取得する @@ -15,8 +15,8 @@ FFI\CDataptr - Gets the FFI\CType object representing the type of the given - FFI\CData object. + 与えられた FFI\CData オブジェクトの型を表す + FFI\CType オブジェクトを取得します。 @@ -27,7 +27,7 @@ ptr - The handle of the pointer to a C data structure. + C のデータ構造へのポインターのハンドル。 @@ -37,8 +37,8 @@ &reftitle.returnvalues; - Returns the FFI\CType object representing the type of the given - FFI\CData object. + 与えられた FFI\CData オブジェクトの型を表す + FFI\CType オブジェクトを返します。 diff --git a/reference/ffi/setup.xml b/reference/ffi/setup.xml index 0cbae67c74..de9a9a6bbf 100644 --- a/reference/ffi/setup.xml +++ b/reference/ffi/setup.xml @@ -1,6 +1,6 @@ - + &reftitle.setup; @@ -8,8 +8,8 @@
&reftitle.required; - This extension requires the libffi library - to be installed. + この拡張には、libffi library の + インストールが必要です。
@@ -62,15 +62,16 @@ - Allows enabling ("true") or disabling - ("false") FFI API usage, or restricting it only to - the CLI SAPI and preloaded files ("preload"). + FFI API の使用を有効化する ("true") か + 無効化する ("false") か、 + CLI SAPI と事前ロードファイルでだけ使えるよう制限する ("preload") かを + 指定します。 - The FFI API restrictions only affect the FFI class, - but not overloaded functions of FFI\CData objects. - This means that it is possible to create some FFI\CData - objects in preloaded files, and then to use these directly in PHP scripts. + FFI API の利用制限は、FFI クラスにのみ影響し、 + FFI\CData オブジェクトのオーバーロードされた関数には影響しません。 + つまり、事前ロードファイルで FFI\CData オブジェクトを作成し、 + それを PHP スクリプトで直接使うことは可能だということです。 @@ -81,10 +82,11 @@ - Allows preloading of FFI bindings during startup, which is not possible with FFI::load - if opcache.preload_user is set. - This directive accepts a DIRECTORY_SEPARATOR delimited list of filenames. - The preloaded bindings can be accessed by calling FFI::scope. + FFI バインディングを起動時に事前ロードできるようにします。 + opcache.preload_user が設定されている場合、 + FFI の事前ロードを FFI::load で実現することはできません。 + このディレクティブは DIRECTORY_SEPARATOR で区切られたファイル名のリストを受け付けます。 + 事前ロードされたバインディングは FFI::scope を呼ぶことでアクセスできます。