summaryrefslogtreecommitdiff
path: root/ext/dl/doc/dl.txt
diff options
context:
space:
mode:
authorttate <ttate@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2002-04-11 07:09:33 +0000
committerttate <ttate@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2002-04-11 07:09:33 +0000
commit2990a0015324117f847bd2089ce945215cb23b4f (patch)
tree1c6ce3b221101cfdc1b77a2745cdc567be9a2575 /ext/dl/doc/dl.txt
parent27a30bbf18c4a266fcbbe13f95bce8c352604afa (diff)
Add dl.txt instead of README.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2359 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/dl/doc/dl.txt')
-rw-r--r--ext/dl/doc/dl.txt250
1 files changed, 250 insertions, 0 deletions
diff --git a/ext/dl/doc/dl.txt b/ext/dl/doc/dl.txt
new file mode 100644
index 0000000000..88c8b2d776
--- /dev/null
+++ b/ext/dl/doc/dl.txt
@@ -0,0 +1,250 @@
+=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 to 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 the timeval structure.
+ "long tv_sec",
+ "long tv_uses",
+ ]
+ end
+ val = LIBC::Timeval.new # allocate the memory.
+
+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, [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, I, L, D and P.
+for example:
+
+ DL.set_callback('IPP',0){|ptr1,ptr2|
+ str1 = ptr1.ptr.to_s
+ str2 = ptr2.ptr.to_s
+ return str1 <=> str2
+ }
+=end