1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

Add dl.txt instead of README.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2359 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
ttate 2002-04-11 07:09:33 +00:00
parent 27a30bbf18
commit 2990a00153
3 changed files with 268 additions and 8 deletions

View file

@ -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.

View file

@ -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

250
ext/dl/doc/dl.txt Normal file
View file

@ -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