summaryrefslogtreecommitdiff
path: root/ext/dl/doc/dl.txt
diff options
context:
space:
mode:
authorttate <ttate@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2005-02-04 13:29:49 +0000
committerttate <ttate@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2005-02-04 13:29:49 +0000
commit4ae9132605dc7b0297bcda408ca7a2ad7de39d2f (patch)
tree6ab98b3252accf7357660e1668bf9e37883340bc /ext/dl/doc/dl.txt
parent889ca023e33ae35c259d02912187ac31be4f5362 (diff)
remove all files to replace ruby-dl with ruby-dl2.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@7882 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/dl/doc/dl.txt')
-rw-r--r--ext/dl/doc/dl.txt266
1 files changed, 0 insertions, 266 deletions
diff --git a/ext/dl/doc/dl.txt b/ext/dl/doc/dl.txt
deleted file mode 100644
index 893bd21d79..0000000000
--- a/ext/dl/doc/dl.txt
+++ /dev/null
@@ -1,266 +0,0 @@
-=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 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 timeval structure.
- "long tv_sec",
- "long tv_uses",
- ]
- end
- val = LIBC::Timeval.malloc # allocate memory.
-
-Notice that the above example takes LIBC::Timeval.malloc to allocate memory,
-rather than LIBC::Timeval.new. It is because DL::Timeval.new is for wrapping
-an object, PtrData, which has already been created.
-
-We can define a callback using the module function "callback" as follows:
-
- module Foo
- extend DL::Importable
- def my_comp(str1,str2)
- str1 <=> str2
- end
- COMPARE = callback "int my_comp(char*,char*)"
- end
-
-where Foo::COMPARE is a Symbol object which invokes the method "my_comp".
-
-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, [size = 0, 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 : char
- c : char *
- H : short
- h : short *
- I : int
- i : int *
- L : long
- l : long *
- F : float
- f : float *
- D : double
- d : double *
- S : const char *
- s : char *
- A : const type[]
- a : type[] (allocates new memory space)
- P : void * (same as 'p')
- p : void * (same as 'P')
- 0 : void function (this must be a first character of the prototype)
-
-the cbtype consists of type specifiers 0, C, I, H, L, F, D, S and P.
-for example:
-
- DL.callback('IPP'){|ptr1,ptr2|
- str1 = ptr1.ptr.to_s
- str2 = ptr2.ptr.to_s
- str1 <=> str2
- }
-=end