-
Notifications
You must be signed in to change notification settings - Fork 333
Types
Benoit Daloze edited this page Apr 1, 2024
·
23 revisions
This page contains a canonical list of type symbols recognized by attach_function and Struct#layout
The following types can be used as arguments and return types:
Symbol | Description | Expected/returned type from FFI | Notes |
---|---|---|---|
:char |
8-bit character | Integer | |
:uchar |
8-bit unsigned character | Integer | |
:int8 |
8-bit signed integer | Integer | |
:uint8 |
8-bit unsigned integer | Integer | |
:short |
16-bit signed integer | Integer | |
:ushort |
16-bit unsigned integer | Integer | |
:int16 |
16-bit signed integer | Integer | |
:uint16 |
16-bit unsigned integer | Integer | |
:int |
signed integer | Integer | platform specific size |
:uint |
unsigned integer | Integer | platform specific size |
:int32 |
32-bit signed integer | Integer | |
:uint32 |
32-bit unsigned integer | Integer | |
:long |
long int | Integer | platform-specific size |
:ulong |
unsigned long int | Integer | platform-specific size |
:int64 |
64-bit signed integer | Integer | |
:uint64 |
64-bit unsigned integer | Integer | |
:long_long |
64-bit signed integer | Integer | |
:ulong_long |
64-bit unsigned integer | Integer | |
:float |
32-bit floating point | Float | |
:double |
64-bit floating point (double-precision) | Float | |
:pointer |
pointer with platform-specific size | out: FFI::Pointer in: FFI::Pointer, String, Integer |
Data may contain zero bytes and may not be zero-terminated. Ruby Strings can be passed directly to C, but should be considered read-only on both Ruby and C side. |
:string |
C-style (NULL-terminated) character string. | String |
:string should be considered to be const char * and the Ruby string must not be changed as long as it’s accessed by the library. If the string buffer shall be modified from C or Ruby side, use a FFI::MemoryPointer with the :pointer type instead. |
:bool |
boolean |
true /false
|
|
Enums | your own custom enum group (or its symbol) as a type | Symbol/Integer |
For function return type only:
Symbol | Description | Returned type from FFI | Notes |
---|---|---|---|
:void |
return type void
|
Pointer | for functions that return nothing |
:strptr |
Ruby String and a Pointer to C memory | Array (e.g. ["foo", ptr] ) |
useful to free the memory from within Ruby |
For function argument type only:
Symbol | Description | Expected by FFI | Notes |
---|---|---|---|
:buffer_in |
Similar to :pointer , but optimized for Buffers that the function can only read (not write). |
FFI::Pointer | |
:buffer_out |
Similar to :pointer , but optimized for Buffers that the function can only write (not read). |
FFI::Pointer | |
:buffer_inout |
Similar to :pointer , but may be optimized for Buffers. |
FFI::Pointer | |
:varargs |
variadic arguments | anything | see examples |
See also Core-Concepts for details about the memory management of :pointer, :string and :buffer types.
Most common C types like :size_t
, :uint32_t
and :in_addr_t
are predefined. For a full list see lib/ffi/platform/<your platform>/types.conf
in the git repository.
Furthermore it’s possible to define your own types. This is particular useful to distinguish between different :pointer
types like so:
typedef :pointer, :libusb_device_handle
attach_function 'libusb_reset_device', [:libusb_device_handle], :int
There are even more nice possibilities to map values:
- Mapping of structs with optional type safety
- Definition of your own data converters
See this blog post for more information.