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_BOOL

ALIGN_BOOL

The alignment size of a bool

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

Public Class Methods

dlopen (library)

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 79
def dlopen library
  Fiddle::Handle.new(library)
rescue DLError => error
  case error.message
  when /\A(\/.+?): (?:invalid ELF header|file too short)/
    # This may be a linker script:
    # https://sourceware.org/binutils/docs/ld.html#Scripts
    path = $1
  else
    raise
  end

  File.open(path) do |input|
    input.each_line do |line|
      case line
      when /\A\s*(?:INPUT|GROUP)\s*\(\s*([^\s,\)]+)/
        # TODO: Should we support multiple files?
        first_input = $1
        if first_input.start_with?("-l")
          first_input = "lib#{first_input[2..-1]}.so"
        end
        return dlopen(first_input)
      end
    end
  end

  # Not found
  raise
end

dlunwrap(addr)

Source

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

Returns the Ruby object stored at the memory address addr

Example:

x = Object.new
# => #<Object:0x0000000107c7d870>
Fiddle.dlwrap(x)
# => 4425504880
Fiddle.dlunwrap(_)
# => #<Object:0x0000000107c7d870>

dlwrap(val)

Source

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

Returns the memory address of the Ruby object stored at val

Example:

x = Object.new
# => #<Object:0x0000000107c7d870>
Fiddle.dlwrap(x)
# => 4425504880

In the case val is not a heap allocated object, this method will return the tagged pointer value.

Example:

Fiddle.dlwrap(123)
# => 247

free(addr)

Source

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

    ruby_xfree(ptr);
    return Qnil;
}

Free the memory at address addr

last_error ()

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 14
def self.last_error
  FFI.errno
end

last_error= (error)

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 18
def self.last_error=(error)
  FFI.errno = error || 0
end

malloc(size)

Source

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

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

realloc(addr, size)

Source

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);
}

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.

win32_last_error ()

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 24
def win32_last_error
  FFI.errno.nonzero?
end

win32_last_error= (error)

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 27
def win32_last_error=(error)
  FFI.errno = error || 0
end

win32_last_socket_error ()

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 31
def win32_last_socket_error
  FFI.errno.nonzero?
end

win32_last_socket_error= (error)

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 34
def win32_last_socket_error=(error)
  FFI.errno = error || 0
end

Private Instance Methods

dlopen (library)

Source

# File bundled-src/fiddle-1.1.8/lib/fiddle.rb, line 79
def dlopen library
  Fiddle::Handle.new(library)
rescue DLError => error
  case error.message
  when /\A(\/.+?): (?:invalid ELF header|file too short)/
    # This may be a linker script:
    # https://sourceware.org/binutils/docs/ld.html#Scripts
    path = $1
  else
    raise
  end

  File.open(path) do |input|
    input.each_line do |line|
      case line
      when /\A\s*(?:INPUT|GROUP)\s*\(\s*([^\s,\)]+)/
        # TODO: Should we support multiple files?
        first_input = $1
        if first_input.start_with?("-l")
          first_input = "lib#{first_input[2..-1]}.so"
        end
        return dlopen(first_input)
      end
    end
  end

  # Not found
  raise
end