In Files

  • dl/cfunc.c
  • dl/cptr.c
  • dl/dl.c
  • dl/lib/dl.rb
  • dl/lib/dl/callback.rb
  • dl/lib/dl/cparser.rb
  • dl/lib/dl/func.rb
  • dl/lib/dl/import.rb
  • dl/lib/dl/pack.rb
  • dl/lib/dl/stack.rb
  • dl/lib/dl/struct.rb
  • dl/lib/dl/types.rb
  • dl/lib/dl/value.rb

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

See also RUBY_PLATFORM

BUILD_RUBY_VERSION

BUILD_RUBY_VERSION

Ruby Version built. (i.e. "1.9.3")

See also RUBY_VERSION

DLSTACK_SIZE

DLSTACK_SIZE

Dynamic linker stack size

MAX_CALLBACK

MAX_CALLBACK

Maximum number of callbacks

NULL
NULL

A NULL pointer

RTLD_GLOBAL

RTLD_GLOBAL

rtld DL::Handle flag.

The symbols defined by this library will be made available for symbol resolution of subsequently loaded libraries.

RTLD_LAZY

RTLD_LAZY

rtld DL::Handle flag.

Perform lazy binding. Only resolve symbols as the code that references them is executed. If the symbol is never referenced, then it is never resolved. (Lazy binding is only performed for function references; references to variables are always immediately bound when the library is loaded.)

RTLD_NOW

RTLD_NOW

rtld DL::Handle flag.

If this value is specified or the environment variable LD_BIND_NOW is set to a nonempty string, all undefined symbols in the library are resolved before dlopen() returns. If this cannot be done an error is returned.

RUBY_FREE

RUBY_FREE

Address of the ruby_xfree() function

SIZEOF_CHAR

SIZEOF_CHAR

size of a 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_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

DL::CFunc type - char

TYPE_DOUBLE

TYPE_DOUBLE

DL::CFunc type - double

TYPE_FLOAT

TYPE_FLOAT

DL::CFunc type - float

TYPE_INT

TYPE_INT

DL::CFunc type - int

TYPE_INTPTR_T

TYPE_INTPTR_T

DL::CFunc type - intptr_t

TYPE_LONG

TYPE_LONG

DL::CFunc type - long

TYPE_LONG_LONG

TYPE_LONG_LONG

DL::CFunc type - long long

TYPE_PTRDIFF_T

TYPE_PTRDIFF_T

DL::CFunc type - ptrdiff_t

TYPE_SHORT

TYPE_SHORT

DL::CFunc type - short

TYPE_SIZE_T

TYPE_SIZE_T

DL::CFunc type - size_t

TYPE_SSIZE_T

TYPE_SSIZE_T

DL::CFunc type - ssize_t

TYPE_UINTPTR_T

TYPE_UINTPTR_T

DL::CFunc type - uintptr_t

TYPE_VOID

TYPE_VOID

DL::CFunc type - void

TYPE_VOIDP

TYPE_VOIDP

DL::CFunc type - void*

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

    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;

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

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

Public Instance Methods

remove_callback(addr, ctype = nil) click to toggle source
remove_callback_internal(proc_entry, addr_entry, addr, ctype = nil) click to toggle source
 
               # File 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 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 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) click to toggle source
Alias for: set_cdecl_callback
set_callback_internal(proc_entry, addr_entry, argc, ty, abi = nil, &cbp) click to toggle source
 
               # File 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 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 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
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus