Book/ffi-Phpdoc专题

Foreign Function Interface

简介
安装／配置
预定义常量
范例
FFI — Main interface to C code and data
- FFI::addr — Creates an unmanaged pointer to C data
- FFI::alignof — Gets the alignment
- FFI::arrayType — Dynamically constructs a new C array type
- FFI::cast — Performs a C type cast
- FFI::cdef — Creates a new FFI object
- FFI::free — Releases an unmanaged data structure
- FFI::isNull — Checks whether a FFI\CData is a null pointer
- FFI::load — Loads C declarations from a C header file
- FFI::memcmp — Compares memory areas
- FFI::memcpy — Copies one memory area to another
- FFI::memset — Fills a memory area
- FFI::new — Creates a C data structure
- FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
- FFI::sizeof — Gets the size of C data or types
- FFI::string — Creates a PHP string from a memory area
- FFI::type — Creates an FFI\CType object from a C declaration
- FFI::typeof — Gets the FFI\CType of FFI\CData
FFI\CData — C Data Handles
FFI\CType — C Type Handles
FFI\Exception — FFI Exceptions
FFI\ParserException — FFI Parser Exceptions

简介

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.

类摘要

FFI

class FFI {

/* 方法 */

public static FFI\CData addr ( FFI\CData &$ptr )

public static int alignof ( FFI\CDataFFI\CType &$ptr )

public static FFI\CType arrayType ( FFI\CType $type , array $dimensions )

public static FFI\CDatanull cast ( FFI\CTypestring $type , FFI\CDataintfloatboolnull &$ptr )

public FFI\CDatanull cast ( FFI\CTypestring $type , FFI\CDataintfloatboolnull &$ptr )

public static FFI cdef ([ string $code = "" [, stringnull $lib = null ]] )

public static void free ( FFI\CData &$ptr )

public static bool isNull ( FFI\CData &$ptr )

public static FFInull load ( string $filename )

public static int memcmp ( stringFFI\CData &$ptr1 , stringFFI\CData &$ptr2 , int $size )

public static void memcpy ( FFI\CData &$to , FFI\CDatastring &$from , int $size )

public static void memset ( FFI\CData &$ptr , int $value , int $size )

public static FFI\CDatanull new ( FFI\CTypestring $type [, bool $owned = true [, bool $persistent = false ]] )

public FFI\CDatanull new ( FFI\CTypestring $type [, bool $owned = true [, bool $persistent = false ]] )

public static FFI scope ( string $name )

public static int sizeof ( FFI\CDataFFI\CType &$ptr )

public static string string ( FFI\CData &$ptr [, intnull $size = null ] )

public static FFI\CTypenull type ( string $type )

public FFI\CTypenull type ( string $type )

public static FFI\CType typeof ( FFI\CData &$ptr )

}

FFI::addr

Creates an unmanaged pointer to C data

说明

public static FFI\CData FFI::addr ( FFI\CData &$ptr )

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.

参数

ptr
The handle of the pointer to a C data structure.

返回值

Returns the freshly created FFI\CData object.

FFI::alignof

Gets the alignment

说明

public static int FFI::alignof ( FFI\CDataFFI\CType &$ptr )

Gets the alignment of the given FFI\CData or FFI\CType object.

参数

ptr
The handle of the C data or type.

返回值

Returns the alignment of the given FFI\CData or FFI\CType object.

FFI::arrayType

Dynamically constructs a new C array type

说明

public static FFI\CType FFI::arrayType ( FFI\CType $type , array $dimensions )

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:

<?php
$t1 = FFI::type("int[2][3]");
$t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
?>

参数

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.

返回值

Returns the freshly created FFI\CType object.

FFI::cast

Performs a C type cast

说明

public static FFI\CDatanull FFI::cast ( FFI\CTypestring $type , FFI\CDataintfloatboolnull &$ptr )

public FFI\CDatanull FFI::cast ( FFI\CTypestring $type , FFI\CDataintfloatboolnull &$ptr )

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. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

参数

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.

返回值

Returns the freshly created FFI\CData object.

FFI::cdef

Creates a new FFI object

说明

public static FFI FFI::cdef ([ string $code = "" [, stringnull $lib = null ]] )

Creates a new FFI object.

参数

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.

Note:

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.

Note:

If lib is omitted, platforms supporting RTLD_DEFAULT attempt to lookup symbols declared in code in the normal global scope. Other systems will fail to resolve these symbols.

返回值

Returns the freshly created FFI object.

更新日志

版本	说明
8.0.0	`lib` is nullable now.

FFI::free

Releases an unmanaged data structure

说明

public static void FFI::free ( FFI\CData &$ptr )

Manually releases a previously created unmanaged data structure.

参数

ptr
The handle of the unmanaged pointer to a C data structure.

返回值

没有返回值。

FFI::isNull

Checks whether a FFI\CData is a null pointer

说明

public static bool FFI::isNull ( FFI\CData &$ptr )

Checks whether a FFI\CData is a null pointer.

参数

ptr
The handle of the pointer to a C data structure.

返回值

Returns whether a FFI\CData is a null pointer.

FFI::load

Loads C declarations from a C header file

说明

public static FFInull FFI::load ( string $filename )

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.

参数

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".

返回值

Returns the freshly created FFI object, or null on failure.

参见

FFI::scope

FFI::memcmp

Compares memory areas

说明

public static int FFI::memcmp ( stringFFI\CData &$ptr1 , stringFFI\CData &$ptr2 , int $size )

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
The start of one memory area.

ptr2
The start of another memory area.

size
The number of bytes to compare.

返回值

Returns \< 0 if the contents of the memory area starting at ptr1 are considered less than the contents of the memory area starting at ptr2, > 0 if the contents of the first memory area are considered greater than the second, and 0 if they are equal.

FFI::memcpy

Copies one memory area to another

说明

public static void FFI::memcpy ( FFI\CData &$to , FFI\CDatastring &$from , int $size )

Copies size bytes from the memory area from to the memory area to.

参数

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.

返回值

没有返回值。

FFI::memset

Fills a memory area

说明

public static void FFI::memset ( FFI\CData &$ptr , int $value , int $size )

Fills size bytes of the memory area pointed to by ptr with the given byte value.

参数

ptr
The start of the memory area to fill.

value
The byte to fill with.

size
The number of bytes to fill.

返回值

没有返回值。

FFI::new

Creates a C data structure

说明

public static FFI\CDatanull FFI::new ( FFI\CTypestring $type [, bool $owned = true [, bool $persistent = false ]] )

public FFI\CDatanull FFI::new ( FFI\CTypestring $type [, bool $owned = true [, bool $persistent = false ]] )

Creates a native data structure of the given C type. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

参数

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).

返回值

Returns the freshly created FFI\CData object, or null on failure.

FFI::scope

Instantiates an FFI object with C declarations parsed during preloading

说明

public static FFI FFI::scope ( string $name )

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.

参数

name
The scope name defined by a special FFI_SCOPE define.

返回值

Returns the freshly created FFI object.

参见

FFI::load

FFI::sizeof

Gets the size of C data or types

说明

public static int FFI::sizeof ( FFI\CDataFFI\CType &$ptr )

Returns the size of the given FFI\CData or FFI\CType object.

参数

ptr
The handle of the C data or type.

返回值

The size of the memory area pointed at by ptr.

FFI::string

Creates a PHP string from a memory area

说明

public static string FFI::string ( FFI\CData &$ptr [, intnull $size = null ] )

Creates a PHP string from size bytes of the memory area pointed to by ptr.

参数

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, ptr must be a zero terminated array of C chars.

返回值

The freshly created PHP string.

更新日志

版本	说明
8.0.0	`size` is nullable now; previously, its default was 0.

FFI::type

Creates an FFI\CType object from a C declaration

说明

public static FFI\CTypenull FFI::type ( string $type )

public FFI\CTypenull FFI::type ( string $type )

This function creates and returns a FFI\CType object for the given string containing a C type declaration. If this method is called statically, it must only use predefined C type names (e.g. int, char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

参数

type
A valid C declaration as string, or an instance of FFI\CType which has already been created.

返回值

Returns the freshly created FFI\CType object, or null on failure.

FFI::typeof

Gets the FFI\CType of FFI\CData

说明

public static FFI\CType FFI::typeof ( FFI\CData &$ptr )

Gets the FFI\CType object representing the type of the given FFI\CData object.

参数

ptr
The handle of the pointer to a C data structure.

返回值

Returns the FFI\CType object representing the type of the given FFI\CData object.

简介

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.

Note: 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

class FFI\CData {

}

简介

类摘要

FFI\CType

class FFI\CType {

}

简介

类摘要

FFI\Exception

class FFI\Exception extends Error implements Throwable {

/* 继承的属性 */

protected string $message ;

protected int $code ;

protected string $file ;

protected int $line ;

/* 继承的方法 */

final public string Error::getMessage ( void )

final public Throwable Error::getPrevious ( void )

final public mixed Error::getCode ( void )

final public string Error::getFile ( void )

final public int Error::getLine ( void )

final public array Error::getTrace ( void )

final public string Error::getTraceAsString ( void )

public string Error::__toString ( void )

final private void Error::__clone ( void )

}

简介

类摘要

FFI\ParserException

class FFI\ParserException extends FFI\Exception implements Throwable {

/* 继承的属性 */

protected string $message ;

protected int $code ;

protected string $file ;

protected int $line ;

}