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:
parent
27a30bbf18
commit
2990a00153
3 changed files with 268 additions and 8 deletions
|
@ -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.
|
||||
|
|
|
@ -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
250
ext/dl/doc/dl.txt
Normal 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
|
Loading…
Reference in a new issue