From 2990a0015324117f847bd2089ce945215cb23b4f Mon Sep 17 00:00:00 2001 From: ttate Date: Thu, 11 Apr 2002 07:09:33 +0000 Subject: Add dl.txt instead of README. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2359 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 + ext/dl/MANIFEST | 22 +++-- ext/dl/doc/dl.txt | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 268 insertions(+), 8 deletions(-) create mode 100644 ext/dl/doc/dl.txt diff --git a/ChangeLog b/ChangeLog index c0c3dac8d8..db67b1778b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Thu Apr 11 07:02:31 2002 Takaaki Tateishi + + * ext/dl: Add dl.txt instead of README and README.html. + Thu Apr 11 01:55:52 2002 Wakou Aoyama * lib/cgi/session.rb: support for multipart form. diff --git a/ext/dl/MANIFEST b/ext/dl/MANIFEST index a98d6f5b34..c5cd5839a8 100644 --- a/ext/dl/MANIFEST +++ b/ext/dl/MANIFEST @@ -1,24 +1,30 @@ .cvsignore -Changes MANIFEST -README -README.html depend dl.c -dl.h dl.def +dl.h +doc/dl.txt extconf.rb h2rb handle.c +install.rb +lib/dl/import.rb +lib/dl/struct.rb +lib/dl/types.rb +lib/dl/win32.rb mkcall.rb mkcallback.rb mkcbtable.rb ptr.c -sym.c -type.rb -test/test.c -test/test.rb sample/drives.rb sample/getch.rb sample/libc.rb sample/msgbox.rb +sample/msgbox2.rb +sample/stream.rb +sym.c +test/libtest.def +test/test.c +test/test.rb +type.rb 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 -- cgit v1.2.3