267 lines
8.5 KiB
Plaintext
267 lines
8.5 KiB
Plaintext
=begin
|
|
|
|
= Ruby/DL
|
|
|
|
Ruby/DL provides an interface to the dynamic linker such as dlopen() on UNIX
|
|
and LoadLibrary() on Windows.
|
|
|
|
= Building and 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
|
|
|
|
= Using Ruby/DL
|
|
|
|
We should usually use DL::Importable module provided by "dl/import.rb".
|
|
It has high-level functions to access library functions. We use
|
|
DL::Importable module to extend a module as follows:
|
|
|
|
require "dl/import"
|
|
module LIBC
|
|
extend DL::Importable
|
|
end
|
|
|
|
Now we can use methods dlload and extern in this module. We load the
|
|
libraries using dlload, and define wrapper methods to library functions
|
|
using extern respectively as follows:
|
|
|
|
module LIBC
|
|
extend DL::Importable
|
|
dlload "libc.so.6","libm.so.6"
|
|
extern "int strlen(char*)"
|
|
end
|
|
# Note that we should not include the module LIBC from some reason.
|
|
|
|
We can call the library function strlen() using LIBC.strlen. If the first
|
|
character of given function name is an uppercase, the first character of the
|
|
defined method name becomes lowercase.
|
|
We can also construct memory images of structures and unions using functions
|
|
struct and union which are defined in "dl/struct.rb" as follows:
|
|
|
|
require "dl/import"
|
|
require "dl/struct"
|
|
module LIBC
|
|
extend DL::Importable
|
|
Timeval = struct [ # define timeval structure.
|
|
"long tv_sec",
|
|
"long tv_uses",
|
|
]
|
|
end
|
|
val = LIBC::Timeval.malloc # allocate memory.
|
|
|
|
Notice that the above example takes LIBC::Timeval.malloc to allocate memory,
|
|
rather than LIBC::Timeval.new. It is because DL::Timeval.new is for wrapping
|
|
an object, PtrData, which has already been created.
|
|
|
|
We can define a callback using the module function "callback" as follows:
|
|
|
|
module Foo
|
|
extend DL::Importable
|
|
def my_comp(str1,str2)
|
|
str1 <=> str2
|
|
end
|
|
COMPARE = callback "int my_comp(char*,char*)"
|
|
end
|
|
|
|
where Foo::COMPARE is a Symbol object which invokes the method "my_comp".
|
|
|
|
DL::Importable module is very useful. However, we sometimes encounter a case
|
|
that we must directly use low-level functions such as dlsym(). In such case,
|
|
we would use DL module functions. They are described in next section.
|
|
|
|
= DL module
|
|
|
|
Module DL consists of three classes, a few module functions and constants.
|
|
The class Symbol represents the symbol we can call. The class PtrData
|
|
indicates a memory block such as a pointer in C. An object instantiated from
|
|
the class Handle keeps a handle to opened library.
|
|
|
|
== Constants
|
|
|
|
* VERSION
|
|
* MAJOR_VERSION
|
|
* MINOR_VERSION
|
|
* PATCH_VERSION
|
|
* RTLD_GLOBAL
|
|
* RTLD_LAZY
|
|
* RTLD_NOW
|
|
* MAX_ARG
|
|
* MAX_CBARG
|
|
* MAX_CBENT
|
|
|
|
== 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.
|
|
|
|
== Handle class
|
|
|
|
* 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'.
|
|
|
|
== Symbol class
|
|
|
|
* 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.
|
|
|
|
== PtrData class
|
|
|
|
* ptr = PtrData.new(addr, [size = 0, 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
|
|
|
|
the prototype consists of the following type specifiers, first element of
|
|
prototype represents the type of return value, and remaining elements represent
|
|
the type of each argument.
|
|
|
|
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)
|
|
|
|
the cbtype consists of type specifiers 0, C, I, H, L, F, D, S and P.
|
|
for example:
|
|
|
|
DL.callback('IPP'){|ptr1,ptr2|
|
|
str1 = ptr1.ptr.to_s
|
|
str2 = ptr2.ptr.to_s
|
|
str1 <=> str2
|
|
}
|
|
=end
|