diff --git a/reference/ffi/configure.xml b/reference/ffi/configure.xml index a1434bab0..90755f2c8 100644 --- a/reference/ffi/configure.xml +++ b/reference/ffi/configure.xml @@ -1,5 +1,5 @@ - +
&reftitle.install; diff --git a/reference/ffi/examples.xml b/reference/ffi/examples.xml new file mode 100644 index 000000000..de8440777 --- /dev/null +++ b/reference/ffi/examples.xml @@ -0,0 +1,344 @@ + + + + + &reftitle.examples; +
+ Uso básico da FFI + + Antes de mergulhar nos detalhes da API da FFI, seguem abaixo alguns exemplos + demonstrando a simplicidade de seu uso para tarefas regulares. + + + + Alguns destes exemplos requerem o libc.so.6 e por isso não + funcionarão em sistemas onde ele não estiver disponível. + + + + + Chamando uma função de uma biblioteca compartilhada + +printf("Olá, %s!\n", "mundo"); +?> +]]> + + &example.outputs; + + + + + + + + Observe que algumas funções de C precisam de convenções específicas de chamada, por exemplo __fastcall, + __stdcall ou ,__vectorcall. + + + + + Chamando uma função e retornando uma estrutura através de um argumento + +new("struct timeval"); +$tz = $ffi->new("struct timezone"); +// chama a função C gettimeofday() +var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz))); +// acessa campo da estrutura de dados C +var_dump($tv->tv_sec); +// exibe toda a estrutura de dados C +var_dump($tz); +?> +]]> + + &example.outputs.similar; + + + int(0) + ["tz_dsttime"]=> + int(0) +} +]]> + + + + + + Acessando variáveis C existentes + +errno); +?> +]]> + + &example.outputs; + + + + + + + + Criando e modificando variáveis C + +cdata); + +// atribuição simples +$x->cdata = 5; +var_dump($x->cdata); + +// atribuição composta +$x->cdata += 2; +var_dump($x->cdata); +?> +]]> + + &example.outputs; + + + + + + + + Trabalhando com arrays C + + +]]> + + &example.outputs; + + + + + + + + Trabalhando com enumerações C + +ZEND_FFI_SYM_TYPE); +var_dump($a->ZEND_FFI_SYM_CONST); +var_dump($a->ZEND_FFI_SYM_VAR); +?> +]]> + + &example.outputs; + + + + + +
+
+ Funções de retorno PHP + + É possível atribuir um closure do PHP a uma variável nativa do tipo ponteiro de função + ou passá-lo como um argumento de função: + + Atribuindo um <classname>Closure</classname> PHP a um ponteiro de função 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 "Olá, Mundo 2!\n"; +$zend->zend_write = $orig_zend_write; +echo "Olá, Mundo 3!\n"; +?> +]]> + + &example.outputs; + + + + + Embora isso funciona, esta funcionalidade não é suportada em todas as plataformas libffi, não é eficiente + e apresenta vazamento de recursos ao final da requisição. + + + Portanto, é recomendado minimizar o uso de chamadas de retorno do PHP. + + + +
+ +
+ Um exemplo completo de PHP/FFI/pré-carregamento + + php.ini + + + + preload.php + + +]]> + + dummy.h + + + + dummy.php + +printf($format, ...$args); + } +} +?> +]]> + + test.php + +printf("Olá, %s!\n", "mundo"); +?> +]]> + + +
+
+ + diff --git a/reference/ffi/ffi.cdata.xml b/reference/ffi/ffi.cdata.xml new file mode 100644 index 000000000..4a6ddb7ed --- /dev/null +++ b/reference/ffi/ffi.cdata.xml @@ -0,0 +1,161 @@ + + + + + Identificadores de dados em C + FFI\CData + + + + +
+ &reftitle.intro; + + Objetos FFI\CData podem ser usados de várias maneiras como dados + + comuns do PHP: + + + + Dados em C de tipos escalares podem ser lidos e atribuídos através da propriedade $cdata, por exemplo, + $x = FFI::new('int'); $x->cdata = 42; + + + + + Campos de estruturas e uniões em C podem ser acessados como uma propriedade comum de objeto PHP, por exemplo, + $cdata->field + + + + + Elementos de array em C podem ser acessados como elementos de array comuns do PHP, por exemplo, + $cdata[$offset] + + + + + Arrays em C podem ser iterados usando instruções &foreach;. + + + + + Arrays em C podem ser usados como argumentos de count. + + + + + Ponteiros em C podem ser desreferenciados como arrays, por exemplo, $cdata[0] + + + + + Ponteiros em C podem ser comparados usando operadores comuns de comparação (<, + <=, ==, !=, >=, >). + + + + + Ponteiros em C podem ser incrementados e decrementads usando as operações comuns +/-/ + ++/--, por exemplo, $cdata += 5 + + + + + Ponteiros em C podem ser subtraídos de outros usando operações normais de subtração -. + + + + + Ponteiros para funções em C podem ser chamados como closures normais de PHP, por exemplo, $cdata() + + + + + Qualquer dado em C pode ser duplicado usando o operador clone, + por exemplo, $cdata2 = clone $cdata; + + + + + Qualquer dado em C pode ser visualizado usando var_dump, print_r etc. + + + + + FFI\CData agora pode ser atribuído a estruturas e campos a partir do PHP 8.3.0. + + + + + + Limitações notáveis são: instâncias FFI\CData não suportam + isset, empty e unset; + e estruturas e uniões C encapsuladas não implementam Traversable. + + + +
+ + +
+ &reftitle.classsynopsis; + + + + + final + FFI\CData + + + + +
+ +
+ &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + FFI\CData agora pode ser atribuído a estruturas e campos. + + + + + +
+ +
+ + + +
+ diff --git a/reference/ffi/ffi.ctype.xml b/reference/ffi/ffi.ctype.xml new file mode 100644 index 000000000..14a7e438f --- /dev/null +++ b/reference/ffi/ffi.ctype.xml @@ -0,0 +1,563 @@ + + + + + Identificadores de Tipo em 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 000000000..14b174a24 --- /dev/null +++ b/reference/ffi/ffi.exception.xml @@ -0,0 +1,74 @@ + + + + + Exceções 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 000000000..46894a2fa --- /dev/null +++ b/reference/ffi/ffi.parserexception.xml @@ -0,0 +1,75 @@ + + + + + Exceções do Analisador 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 000000000..d34d58322 --- /dev/null +++ b/reference/ffi/ffi.xml @@ -0,0 +1,99 @@ + + + + + Interface principal ao código e aos dados em C + FFI + + + + +
+ &reftitle.intro; + + Os objetos desta classe são criados pelos métodos de construção FFI::cdef, + FFI::load ou FFI::scope. Variáveis ​​C definidas + são disponibilizadas como propriedades da instância FFI e funções C definidas são disponibilizadas + como métodos da instância FFI. Os tipos C declarados podem ser usados ​​para criar novas estruturas de dados C + usando FFI::new e FFI::type. + + + A análise da definição FFI e o carregamento da biblioteca compartilhada podem levar um tempo significativo. Não é útil + fazer isso em cada solicitação HTTP em um ambiente Web. Entretanto, é possível pré-carregar definições e + bibliotecas FFI na inicialização do PHP e instanciar objetos FFI quando necessário. Os arquivos de cabeçalho + podem ser estendidos com definições especiais de FFI_SCOPE (por exemplo, #define FFI_SCOPE "foo"; + o escopo padrão é "C") e então carregados por FFI::load durante o pré-carregamento. + Isto leva à criação de uma ligação persistente, que estará disponível para todas as solicitações + seguintes através de FFI::scope. + Consulte o exemplo completo de PHP/FFI/pré-carregamento + para obter detalhes. + + + É possível pré-carregar mais de um arquivo de cabeçalho C no mesmo escopo. + +
+ + +
+ &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/setup.xml b/reference/ffi/setup.xml new file mode 100644 index 000000000..4226066db --- /dev/null +++ b/reference/ffi/setup.xml @@ -0,0 +1,115 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + + Esta extensão precisa que a biblioteca libffi + esteja instalada. + +
+ + + &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 + + + + Permite habilitar ("true") ou desabilitar + ("false") o uso da API FFI, ou restringi-la apenas à + SAPI CLI e arquivos pré-carregados ("preload"). + + + As restrições da API FFI afetam apenas a classe FFI, + mas não as funções sobrecarregadas dos objetos FFI\CData. + Isto significa que é possível criar alguns objetos FFI\CData + em arquivos pré-carregados e então usá-los diretamente em scripts PHP. + + + + + + ffi.preload + string + + + + Permite o pré-carregamento de ligações FFI durante a inicialização, o que não é possível com FFI::load + se opcache.preload_user estiver definida. + Esta diretiva aceita uma lista delimitada de nomes de arquivos por DIRECTORY_SEPARATOR. + As ligações pré-carregadas podem ser acessadas chamando FFI::scope. + + + + + +
+ +
+ +