Add dl.txt instead of README.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2359 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 268 insertions, 8 deletions

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 <ttate@kt.jaist.ac.jp>
+
+	* ext/dl: Add dl.txt instead of README and README.html.
+
 Thu Apr 11 01:55:52 2002  Wakou Aoyama  <wakou@fsinet.or.jp>
 
 	* 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