module DL

A bridge to the dlopen() or dynamic library linker function.

Example¶ ↑

bash $> cat > sum.c <<EOF
double sum(double *arry, int len)
{
        double ret = 0;
        int i;
        for(i = 0; i < len; i++){
                ret = ret + arry[i];
        }
        return ret;
}

double split(double num)
{
        double ret = 0;
        ret = num / 2;
        return ret;
}
EOF
bash $> gcc -o libsum.so -shared sum.c
bash $> cat > sum.rb <<EOF
require 'dl'
require 'dl/import'

module LibSum
        extend DL::Importer
        dlload './libsum.so'
        extern 'double sum(double*, int)'
        extern 'double split(double)'
end

a = [2.0, 3.0, 4.0]

sum = LibSum.sum(a.pack("d*"), a.count)
p LibSum.split(sum)
EOF
bash $> ruby sum.rb
4.5

WIN! :-)

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_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(so_lib) click to toggle source

An interface to the dynamic linking loader

This is a shortcut to DL::Handle.new and takes the same arguments.

Example:

libc_so = "/lib64/libc.so.6"
=> "/lib64/libc.so.6"

libc = DL.dlopen(libc_so)
=> #<DL::Handle:0x00000000e05b00>

VALUE
rb_dl_dlopen(int argc, VALUE argv[], VALUE self)
{
    return rb_class_new_instance(argc, argv, rb_cDLHandle);
}

dlunwrap(addr) click to toggle source

Returns the hexadecimal representation of a memory pointer address addr

Example:

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

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

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

VALUE
rb_dl_ptr2value(VALUE self, VALUE addr)
{
    rb_secure(4);
    return (VALUE)NUM2PTR(addr);
}

dlwrap(val) click to toggle source

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

Example:

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

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

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

fiddle?() click to toggle source

Returns true if DL is using Fiddle, the libffi wrapper.

# File ext/dl/lib/dl.rb, line 12
def self.fiddle?
  Object.const_defined?(:Fiddle)
end

free(addr) click to toggle source

Free the memory at address addr

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

    rb_secure(4);
    ruby_xfree(ptr);
    return Qnil;
}

malloc(size) click to toggle source

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

VALUE
rb_dl_malloc(VALUE self, VALUE size)
{
    void *ptr;

    rb_secure(4);
    ptr = (void*)ruby_xmalloc(NUM2INT(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.

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

    rb_secure(4);
    ptr = (void*)ruby_xrealloc(ptr, NUM2INT(size));
    return PTR2NUM(ptr);
}

Public Instance Methods

remove_callback(addr, ctype = nil)

Alias for: remove_cdecl_callback

remove_callback_internal(proc_entry, addr_entry, addr, ctype = nil) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 70
def remove_callback_internal(proc_entry, addr_entry, addr, ctype = nil)
  if DL.fiddle?
    addr = addr.to_i
    return false unless proc_entry.key?(addr)
    proc_entry.delete(addr)
    true
  else
    index = nil
    if( ctype )
      addr_entry[ctype].each_with_index{|xaddr, idx|
        if( xaddr == addr )
          index = idx
        end
      }
    else
      addr_entry.each{|ty,entry|
        entry.each_with_index{|xaddr, idx|
          if( xaddr == addr )
            index = idx
          end
        }
      }
    end
    if( index and proc_entry[ctype][index] )
      proc_entry[ctype][index] = nil
      return true
    else
      return false
    end
  end
end

remove_cdecl_callback(addr, ctype = nil) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 102
def remove_cdecl_callback(addr, ctype = nil)
  remove_callback_internal(CdeclCallbackProcs, CdeclCallbackAddrs, addr, ctype)
end

Also aliased as: remove_callback

remove_stdcall_callback(addr, ctype = nil) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 106
def remove_stdcall_callback(addr, ctype = nil)
  remove_callback_internal(StdcallCallbackProcs, StdcallCallbackAddrs, addr, ctype)
end

set_callback(ty, argc, &cbp)

Alias for: set_cdecl_callback

set_callback_internal(proc_entry, addr_entry, argc, ty, abi = nil, &cbp) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 30
def set_callback_internal(proc_entry, addr_entry, argc, ty, abi = nil, &cbp)
  if( argc < 0 )
    raise(ArgumentError, "arity should not be less than 0.")
  end
  addr = nil

  if DL.fiddle?
    abi ||= Fiddle::Function::DEFAULT
    closure = Fiddle::Closure::BlockCaller.new(ty, [TYPE_VOIDP] * argc, abi, &cbp)
    proc_entry[closure.to_i] = closure
    addr = closure.to_i
  else
    SEM.synchronize{
      ary = proc_entry[ty]
      (0...MAX_CALLBACK).each{|n|
        idx = (n * DLSTACK_SIZE) + argc
        if( ary[idx].nil? )
          ary[idx] = cbp
          addr = addr_entry[ty][idx]
          break
        end
      }
    }
  end

  addr
end

set_cdecl_callback(ty, argc, &cbp) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 58
def set_cdecl_callback(ty, argc, &cbp)
  set_callback_internal(CdeclCallbackProcs, CdeclCallbackAddrs, argc, ty, &cbp)
end

Also aliased as: set_callback

set_stdcall_callback(ty, argc, &cbp) click to toggle source

# File ext/dl/lib/dl/callback.rb, line 62
def set_stdcall_callback(ty, argc, &cbp)
  if DL.fiddle?
    set_callback_internal(StdcallCallbackProcs, StdcallCallbackAddrs, argc, ty, Fiddle::Function::STDCALL, &cbp)
  else
    set_callback_internal(StdcallCallbackProcs, StdcallCallbackAddrs, argc, ty, &cbp)
  end
end