module Fiddle - RDoc Documentation

# module Fiddle

A libffi wrapper for Ruby.

## Description¶ ↑

`Fiddle` is an extension to translate a foreign function interface (FFI) with ruby.

It wraps libffi, a popular C library which provides a portable interface that allows code written in one language to call code written in another language.

## Example¶ ↑

Here we will use `Fiddle::Function` to wrap floor(3) from libm

    require 'fiddle'

    libm = Fiddle.dlopen('/lib/libm.so.6')

    floor = Fiddle::Function.new(
      libm['floor'],
      [Fiddle::TYPE_DOUBLE],
      Fiddle::TYPE_DOUBLE
    )

    puts floor.call(3.14159) #=> 3.0

### Constants

ALIGN_CHAR

  `ALIGN_CHAR`

  The alignment size of a char

ALIGN_DOUBLE

  `ALIGN_DOUBLE`

  The alignment size of a double

ALIGN_FLOAT

  `ALIGN_FLOAT`

  The alignment size of a float

ALIGN_INT

  `ALIGN_INT`

  The alignment size of an int

ALIGN_INT16_T

  `ALIGN_INT16_T`

  The alignment size of a int16_t

ALIGN_INT32_T

  `ALIGN_INT32_T`

  The alignment size of a int32_t

ALIGN_INT64_T

  `ALIGN_INT64_T`

  The alignment size of a int64_t

ALIGN_INT8_T

  `ALIGN_INT8_T`

  The alignment size of a int8_t

ALIGN_INTPTR_T

  `ALIGN_INTPTR_T`

  The alignment size of a intptr_t

ALIGN_LONG

  `ALIGN_LONG`

  The alignment size of a long

ALIGN_LONG_LONG

  `ALIGN_LONG_LONG`

  The alignment size of a long long

ALIGN_PTRDIFF_T

  `ALIGN_PTRDIFF_T`

  The alignment size of a ptrdiff_t

ALIGN_SHORT

  `ALIGN_SHORT`

  The alignment size of a short

ALIGN_SIZE_T

  `ALIGN_SIZE_T`

  The alignment size of a size_t

ALIGN_SSIZE_T

  `ALIGN_SSIZE_T`

  The alignment size of a ssize_t

ALIGN_UINTPTR_T

  `ALIGN_UINTPTR_T`

  The alignment size of a uintptr_t

ALIGN_VOIDP

  `ALIGN_VOIDP`

  The alignment size of a void*

BUILD_RUBY_PLATFORM

  `BUILD_RUBY_PLATFORM`

  Platform built against (i.e. “x86_64-linux”, etc.)

  See also RUBY_PLATFORM

RUBY_FREE

  `RUBY_FREE`

  Address of the ruby_xfree() function

SIZEOF_CHAR

  `SIZEOF_CHAR`

  size of a char

SIZEOF_CONST_STRING

  `SIZEOF_CONST_STRING`

  size of a const char*

SIZEOF_DOUBLE

  `SIZEOF_DOUBLE`

  size of a double

SIZEOF_FLOAT

  `SIZEOF_FLOAT`

  size of a float

SIZEOF_INT

  `SIZEOF_INT`

  size of an int

SIZEOF_INT16_T

  `SIZEOF_INT16_T`

  size of a int16_t

SIZEOF_INT32_T

  `SIZEOF_INT32_T`

  size of a int32_t

SIZEOF_INT64_T

  `SIZEOF_INT64_T`

  size of a int64_t

SIZEOF_INT8_T

  `SIZEOF_INT8_T`

  size of a int8_t

SIZEOF_INTPTR_T

  `SIZEOF_INTPTR_T`

  size of a intptr_t

SIZEOF_LONG

  `SIZEOF_LONG`

  size of a long

SIZEOF_LONG_LONG

  `SIZEOF_LONG_LONG`

  size of a long long

SIZEOF_PTRDIFF_T

  `SIZEOF_PTRDIFF_T`

  size of a ptrdiff_t

SIZEOF_SHORT

  `SIZEOF_SHORT`

  size of a short

SIZEOF_SIZE_T

  `SIZEOF_SIZE_T`

  size of a size_t

SIZEOF_SSIZE_T

  `SIZEOF_SSIZE_T`

  size of a ssize_t

SIZEOF_UINTPTR_T

  `SIZEOF_UINTPTR_T`

  size of a uintptr_t

SIZEOF_VOIDP

  `SIZEOF_VOIDP`

  size of a void*

TYPE_CHAR

  `TYPE_CHAR`

  C type - char

TYPE_CONST_STRING

  `TYPE_CONST_STRING`

  C type - const char* ('0' terminated const char*)

TYPE_DOUBLE

  `TYPE_DOUBLE`

  C type - double

TYPE_FLOAT

  `TYPE_FLOAT`

  C type - float

TYPE_INT

  `TYPE_INT`

  C type - int

TYPE_INT16_T

  `TYPE_INT16_T`

  C type - int16_t

TYPE_INT32_T

  `TYPE_INT32_T`

  C type - int32_t

TYPE_INT64_T

  `TYPE_INT64_T`

  C type - int64_t

TYPE_INT8_T

  `TYPE_INT8_T`

  C type - int8_t

TYPE_INTPTR_T

  `TYPE_INTPTR_T`

  C type - intptr_t

TYPE_LONG

  `TYPE_LONG`

  C type - long

TYPE_LONG_LONG

  `TYPE_LONG_LONG`

  C type - long long

TYPE_PTRDIFF_T

  `TYPE_PTRDIFF_T`

  C type - ptrdiff_t

TYPE_SHORT

  `TYPE_SHORT`

  C type - short

TYPE_SIZE_T

  `TYPE_SIZE_T`

  C type - size_t

TYPE_SSIZE_T

  `TYPE_SSIZE_T`

  C type - ssize_t

TYPE_UINTPTR_T

  `TYPE_UINTPTR_T`

  C type - uintptr_t

TYPE_VARIADIC

  `TYPE_VARIADIC`

  C type - …

TYPE_VOID

  `TYPE_VOID`

  C type - void

TYPE_VOIDP

  `TYPE_VOIDP`

  C type - void*

VERSION
WINDOWS

  Returns a boolean regarding whether the host is WIN32

### Public Class Methods

dlopen(library) → Fiddle::Handle click to toggle source

Creates a new handler that opens `library`, and returns an instance of `Fiddle::Handle`.

If `nil` is given for the `library`, Fiddle::Handle::DEFAULT is used, which is the equivalent to RTLD_DEFAULT. See `man 3 dlopen` for more.

    lib = Fiddle.dlopen(nil)

The default is dependent on OS, and provide a handle for all libraries already loaded. For example, in most cases you can use this to access `libc` functions, or ruby functions like `rb_str_new`.

See `Fiddle::Handle.new` for more.

    # File ext/fiddle/lib/fiddle.rb, line 60
    def dlopen library
      Fiddle::Handle.new library
    end

dlunwrap(addr) click to toggle source

Returns the hexadecimal representation of a memory pointer address `addr`

Example:

    lib = Fiddle.dlopen('/lib64/libc-2.15.so')
    => #<Fiddle::Handle:0x00000001342460>

    lib['strcpy'].to_s(16)
    => "7f59de6dd240"

    Fiddle.dlunwrap(Fiddle.dlwrap(lib['strcpy'].to_s(16)))
    => "7f59de6dd240"

    VALUE
    rb_fiddle_ptr2value(VALUE self, VALUE addr)
    {
        return (VALUE)NUM2PTR(addr);
    }

dlwrap(val) click to toggle source

Returns a memory pointer of a function's hexadecimal address location `val`

Example:

    lib = Fiddle.dlopen('/lib64/libc-2.15.so')
    => #<Fiddle::Handle:0x00000001342460>

    Fiddle.dlwrap(lib['strcpy'].to_s(16))
    => 25522520

    static VALUE
    rb_fiddle_value2ptr(VALUE self, VALUE val)
    {
        return PTR2NUM((void*)val);
    }

free(addr) click to toggle source

Free the memory at address `addr`

    VALUE
    rb_fiddle_free(VALUE self, VALUE addr)
    {
        void *ptr = NUM2PTR(addr);

        ruby_xfree(ptr);
        return Qnil;
    }

last_error() click to toggle source

Returns the last `Error` of the current executing `Thread` or nil if none

    # File ext/fiddle/lib/fiddle.rb, line 35
    def self.last_error
      Thread.current[:__FIDDLE_LAST_ERROR__]
    end

last_error=(error) click to toggle source

Sets the last `Error` of the current executing `Thread` to `error`

    # File ext/fiddle/lib/fiddle.rb, line 40
    def self.last_error= error
      Thread.current[:__DL2_LAST_ERROR__] = error
      Thread.current[:__FIDDLE_LAST_ERROR__] = error
    end

malloc(size) click to toggle source

Allocate `size` bytes of memory and return the integer memory address for the allocated memory.

    static VALUE
    rb_fiddle_malloc(VALUE self, VALUE size)
    {
        void *ptr;
        ptr = (void*)ruby_xcalloc(1, NUM2SIZET(size));
        return PTR2NUM(ptr);
    }

realloc(addr, size) click to toggle source

Change the size of the memory allocated at the memory location `addr` to `size` bytes. Returns the memory address of the reallocated memory, which may be different than the address passed in.

    static VALUE
    rb_fiddle_realloc(VALUE self, VALUE addr, VALUE size)
    {
        void *ptr = NUM2PTR(addr);

        ptr = (void*)ruby_xrealloc(ptr, NUM2SIZET(size));
        return PTR2NUM(ptr);
    }

win32_last_error() click to toggle source

Returns the last win32 `Error` of the current executing `Thread` or nil if none

    # File ext/fiddle/lib/fiddle.rb, line 12
    def self.win32_last_error
      Thread.current[:__FIDDLE_WIN32_LAST_ERROR__]
    end

win32_last_error=(error) click to toggle source

Sets the last win32 `Error` of the current executing `Thread` to `error`

    # File ext/fiddle/lib/fiddle.rb, line 17
    def self.win32_last_error= error
      Thread.current[:__FIDDLE_WIN32_LAST_ERROR__] = error
    end

win32_last_socket_error() click to toggle source

Returns the last win32 socket `Error` of the current executing `Thread` or nil if none

    # File ext/fiddle/lib/fiddle.rb, line 23
    def self.win32_last_socket_error
      Thread.current[:__FIDDLE_WIN32_LAST_SOCKET_ERROR__]
    end

win32_last_socket_error=(error) click to toggle source

Sets the last win32 socket `Error` of the current executing `Thread` to `error`

    # File ext/fiddle/lib/fiddle.rb, line 29
    def self.win32_last_socket_error= error
      Thread.current[:__FIDDLE_WIN32_LAST_SOCKET_ERROR__] = error
    end

### Private Instance Methods

dlopen(library) → Fiddle::Handle click to toggle source

Creates a new handler that opens `library`, and returns an instance of `Fiddle::Handle`.

If `nil` is given for the `library`, Fiddle::Handle::DEFAULT is used, which is the equivalent to RTLD_DEFAULT. See `man 3 dlopen` for more.

    lib = Fiddle.dlopen(nil)

The default is dependent on OS, and provide a handle for all libraries already loaded. For example, in most cases you can use this to access `libc` functions, or ruby functions like `rb_str_new`.

See `Fiddle::Handle.new` for more.

    # File ext/fiddle/lib/fiddle.rb, line 60
    def dlopen library
      Fiddle::Handle.new library
    end