Ruby/DL

Installing

$ ruby extconf.rb    # to create the Makefile
$ make               # to build the library 'dl.so'
$ make libtest.so    # to build the C library 'libtest.so' for the test script
$ make test          # to run the test script
$ make install       # to install the library
$ make clean         # to remove the created files without Makefile
$ make distclean     # to remove the all created files

Functions and Classes

Constants

Functions

handle = dlopen(lib){|handle| ... }

is quite equal to `Handle.new(lib)'

sym = set_callback(cbtype, entry){|args| ... }

sym = set_callback(cbtype, entry, proc)

makes entry-th pre-defined function to call the proc or given block. the entry-th pre-defined function is specified by cbtype and entry. cbtype is a prototype of the callback. see also the section `Type specifiers' about cbtype.

sym = get_callback(cbtype, entry)

returns the Proc object which is given by the above function `set_callback'.

ptr = malloc(size, [free = nil])

allocates the size bytes, and returns the pointer as a PtrData object ptr.

ptr = strdup(str)

returns a PtrData object ptr which represents the pointer to a new string which is a duplicate of the string str.

size = sizeof(type)

returns the size of type. `sizeof("C") + sizeof("L")' is not equal to `sizeof("CL")'. the latter is assumed to returns the enough size of the structure `struct foo { char c; long l; }', but the size may not equal to `sizeof(foo)' of C.

class Handle

handle = Handle.new(lib){|handle| ... }

opens a library lib and returns a Handle object handle. if a block is given, the handle is automatically closed as the block ends.

Handle#close

closes the handle opened by the above Handle.new(lib).

sym = Handle#sym(func, prototype = "0")

sym = Handle#[func, prototype = nil]

obtains the pointer to a function called func and returns a Symbol object or a DataPtr object. prototype is a string which consists of type specifiers, it indicates the function's prototype. see also the section `Type specifiers'.

class Symbol

sym = Symbol.new(addr, type = nil, name = nil)

creates the Symbol object sym with the type type if type is not nil. addr is the address where the function is allocated. If type is nil, it returns a DataPtr object.

Symbol::char2type(char)

takes a character char that represents a type and returns the type specifier of the C language.

str = Symbol#proto()

returns the function prototype.

str = Symbol#name()

Returns the function name.

str = Symbol#cproto()

str = Symbol#to_s()

returns the prototype of the C language.

str = Symbol#inspect()

returns the inspectable string.

r,rs = Symbol#call(arg1,arg2,...,argN)

r,rs = Symbol#[](arg1,arg2,...,argN)

calls the function with parameters arg1, arg2, ..., argN. and the result consists of the return value r and parameters rs. rs is an array.

ptr = Symbol#to_ptr

returns the corresponding PtrData object ptr.

class PtrData

ptr = PtrData.new(addr, [free = nil])

returns the PtrData object representing the pointer which indicates the address addr. GC frees the memory using the free function.

PtrData#free=(sym)

if you specify a symbol object sym, GC frees the memory using the function represented by sym.

sym = PtrData#free

returns a symbol object sym which is used when GC frees the memory. it usually configured by `PtrData#free=' or `PtrData.new'.

size = PtrData#size, PtrData#size=(size)

gets and sets allocated size of the memory.

ary = PtrData#to_a(type, [size])

returns an array of the type which specified with type. type must be one of 'S','P','I','L','D' and 'F'.

str = PtrData#to_s([len])

returns a string which length is len. if len is omitted, the end of the string is '\0'.

ptr = PtrData#ptr,+@

returns the pointed value as a PtrData object ptr.

ptr = PtrData#ref,-@

returns the reference as a PtrData object ptr.

ptr = PtrData#+

returns the PtrData object

ptr = PtrData#-

returns the PtrData object

PtrData#struct!(type, *members)

defines the data type to get access to a structure member with a symbol. (see also PtrData#[])

PtrData#union!(type, *members)

defines the data type to get access to a union member with a symbol. (see also PtrData#[])

val = PtrData#[key], PtrData#[key, num = 0]

if the key is a string or symbol, this method returns the value of the structure/union member which has the type defined by PtrData#{struct!,union!}. if the key is a integer value and this object represents the pointer ptr, it returns the value of `(ptr + key).to_s(num)'

PtrData#[key,num]=val, PtrData#[key]=val

if the key is a string or symbol, this method substitute the value of the structure/union member with val. if the key is a integer value and val is a string, this method copies num bytes of val to the memory area ptr using memcpy(3).

Type specifiers

C : a character (char)
c : a pointer to a character (char *)
H : a short integer (short)
h : a pointer to a short integer (short *)
I : an integer (char, short, int)
i : a pointer to an integer (char *, short *, int *)
L : a long integer (long)
l : a pointer to a long integer (long *)
F : a real (float)
f : a pointer to a real (float *)
D : a real (double)
d : a pointer to a real (double *)
S : an immutable string (const char *)
s : a mutable string (char *)
A : an array (const type[])
a : a mutable array (type[])
P : a pointer (void *)
p : a mutable object (void *)
0 : void function (this must be a first character of the prototype)

DL.set_callback('IPP',0){|ptr1,ptr2|
  str1 = ptr1.ptr.to_s
  str2 = ptr2.ptr.to_s
  return str1 <=> str2
}