Structure Dynlib


Identifier index Structure index

signature Dynlib =
sig
    type dlHandle
    type symHandle
        
    exception Closed
    
    datatype flag = RTLD_LAZY | RTLD_NOW
    val dlopen  : { lib : string, flag : flag, global : bool } -> dlHandle
    val dlsym   : dlHandle -> string -> symHandle
    val dlclose : dlHandle -> unit

    val var  : symHandle -> 'b                            
    val app1 : symHandle -> 'a1 -> 'b                     
    val app2 : symHandle -> 'a1 -> 'a2 -> 'b              
    val app3 : symHandle -> 'a1 -> 'a2 -> 'a3 -> 'b       
    val app4 : symHandle -> 'a1 -> 'a2 -> 'a3 -> 'a4 -> 'b
    val app5 : symHandle -> 'a1 -> 'a2 -> 'a3 -> 'a4 -> 'a5 -> 'b
end

(* 
   Structure Dynlib provides dynamic loading and calling of C
   functions, using the dlfcn interface.  A dynamic library is a
   collection of symbols (C variables and functions).  

   An ML value passed to or returned from a symbol has type `value' as
   defined in src/runtime/mlvalues.h.  The C functions should use the
   macroes defined there to access and produce ML values.  When
   writing a C function, remember that the garbage collector may be
   activated whenever you allocate an ML value.  Also, remember that
   the garbage collector may move values from the young heap to the
   old one, so that a C pointer pointing into the ML heap may need to
   be updated. Use the Push_roots and Pop_roots macroes to achieve
   this.

   Type [dlHandle] is the type of dynamic library handles.  A dynamic
   library handle is created by opening a dynamic library using
   dlopen.  This will load the library into the runtime system.  The
   dynamic library handle is used for accessing symbols in that
   library.  The library may be closed and removed from the runtime
   system using dlclose.  

   The same library may be opened more than once, resulting in
   different library handles.  The physical library will be loaded
   only once, though, and will remain in the runtime system until all
   handles to the library have been closed.

   Type [symHandle] is the type of symbol handles.  A symbol handle is
   used to access a symbol (variable or function) in the dynamic
   library, using the functions var, app1, app2, ..., app5.  Type
   safety is the responsibility of the programmer; the runtime system
   performs no type checking.  Hence you are advised to add explicit
   types whenever you define an ML function in terms of var, app1,
   ..., app5.

   How to create a dynamically loadable library
   --------------------------------------------
   Assume file "xyz.c" contains your C functions.  

   To compile xyz.c into xyz.o and then create a dynamic library 
   libxyz.so from xyz.o:

     Under Linux and OSF/1 (Digital Unix):
        gcc -c -o xyz.o xyz.c 
        ld -shared -o libxyz.so xyz.o
     Under Solaris (ignore the warnings from ld):
        gcc -c -o xyz.o xyz.c 
        ld -G -B symbolic -z nodefs -o libxyz.so xyz.o
     Under HP-UX:
        gcc -fPIC -c -o xyz.o xyz.c 
        ld -b -B symbolic -E -o libxyz.so xyz.o

   If "xyz.o" depends on another library "libabc.a" you may link the
   required functions into libxyz.so just by adding -labc or libabc.a
   to the above linker command.

   If "xyz.o" depends on another dynamic library "libabc.so" you may
   specify this by adding -labc to the above linker command.  Then
   Dynlib.dlopen will automatically load libabc.so before libxyz.so.


   [dlopen { lib, flag, global }] will load and open the library in
   file `lib', returning a handle to it.  
        If `flag' is RTLD_LAZY, then only symbol relocations will be
   performed now, and function relocations will be performed when each
   function is invoked for the first time (if ever).  This is the
   normal situation.  If `flag' is RTLD_NOW, then all relocations are
   performed immediately, also for functions that will never be
   called.  This may waste some time.  
        If `global' is true, then the library's global symbols are
   made available for other libraries subsequently loaded.
        Libraries are usually specified just by file name, leaving out
   the directory path.  Linux/Unix-specific information: Libraries are
   searched for in those directories mentioned in LD_LIBRARY_PATH,
   those mentioned in /etc/ld.so.cache, in /usr/lib and /lib.  (Note
   that /etc/ld.so.cache is created from /etc/ld.so.conf by running
   ldconfig; you must be superuser to do that).

   [dlsym dlh nam] returns a symbol handle for the symbol called `nam'
   in the library associated with dlh.  Raises Closed if dlh has been
   closed.

   [dlclose dlh] closes the library handle and deallocates the library
   if there are no more open handles to this library.

   The following functions raise Closed if the associated handle has
   been closed.

   [var sym] returns the value of the C variable associated with sym.

   [app1 sym arg1] applies the C function associated with sym to arg1.

   [app2 sym arg1 arg2] applies the C function associated with sym to
   (arg1, arg2).

   [app3 sym arg1 arg2 arg3] applies the C function associated with
   sym to (arg1, arg2, arg3).

   [app4 sym arg1 arg2 arg3 arg4] applies the C function associated
   with sym to (arg1, arg2, arg3, arg4).

   [app5 sym arg1 arg2 arg3 arg4 arg5] applies the C function
   associated with sym to (arg1, arg2, arg3, arg4, arg5). 
*)


Identifier index Structure index


Moscow ML 1.44