3 * Platform: VM/ESA, possibly others which use dllload etc.
4 * Author: Neale Ferguson (neale@mailbox.tabnsw.com.au)
5 * Created: 23rd Septemer, 1998
13 Definition of VM/ESA dynamic Linking functions
14 ==============================================
15 In order to make this implementation easier to understand here is a
16 quick definition of the VM/ESA Dynamic Linking functions which are
22 dlopen(const char *path)
24 This function takes the name of a dynamic object file and returns
25 a descriptor which can be used by dlsym later. It returns NULL on
32 dlsym(void *handle, char *symbol)
34 Takes the handle returned from dlopen and the name of a symbol to
35 get the address of. If the symbol was found a pointer is
36 returned. It returns NULL on error.
42 Returns a null-terminated string which describes the last error
43 that occurred with the other dll functions. After each call to
44 dlerror the error message will be reset to a null pointer. The
45 SaveError function is used to save the error as soo as it happens.
50 In this implementation the two functions, dl_load_file &
51 dl_find_symbol, return void *. This is because the underlying SunOS
52 dynamic linker calls also return void *. This is not necessarily
53 the case for all architectures. For example, some implementation
54 will want to return a char * for dl_load_file.
56 If void * is not appropriate for your architecture, you will have to
57 change the void * to whatever you require. If you are not certain of
58 how Perl handles C data types, I suggest you start by consulting
59 Dean Roerich's Perl 5 API document. Also, have a look in the typemap
60 file (in the ext directory) for a fairly comprehensive list of types
61 that are already supported. If you are completely stuck, I suggest you
62 post a message to perl5-porters, comp.lang.perl.misc or if you are really
65 Remember when you are making any changes that the return value from
66 dl_load_file is used as a parameter in the dl_find_symbol
67 function. Also the return value from find_symbol is used as a parameter
71 Dealing with Error Messages
72 ============================
73 In order to make the handling of dynamic linking errors as generic as
74 possible you should store any error messages associated with your
75 implementation with the StoreError function.
77 In the case of VM/ESA the function dlerror returns the error message
78 associated with the last dynamic link error. As the VM/ESA dynamic
79 linker functions return NULL on error every call to a VM/ESA dynamic
80 dynamic link routine is coded like this
82 RETVAL = dlopen(filename) ;
84 SaveError("%s",dlerror()) ;
86 Note that SaveError() takes a printf format string. Use a "%s" as
87 the first parameter if the error may contain and % characters.
97 #include "dlutils.c" /* SaveError() etc */
103 (void)dl_generic_private_init();
106 MODULE = DynaLoader PACKAGE = DynaLoader
109 (void)dl_private_init();
113 dl_load_file(filename, flags=0)
118 warn("Can't make loaded symbols global on this platform while loading %s",filename);
119 DLDEBUG(1,PerlIO_printf(PerlIO_stderr(), "dl_load_file(%s,%x):\n", filename,flags));
120 RETVAL = dlopen(filename) ;
121 DLDEBUG(2,PerlIO_printf(PerlIO_stderr(), " libref=%lx\n", (unsigned long) RETVAL));
122 ST(0) = sv_newmortal() ;
124 SaveError("%s",dlerror()) ;
126 sv_setiv( ST(0), (IV)RETVAL);
130 dl_find_symbol(libhandle, symbolname)
134 DLDEBUG(2, PerlIO_printf(PerlIO_stderr(),
135 "dl_find_symbol(handle=%lx, symbol=%s)\n",
136 (unsigned long) libhandle, symbolname));
137 RETVAL = dlsym(libhandle, symbolname);
138 DLDEBUG(2, PerlIO_printf(PerlIO_stderr(),
139 " symbolref = %lx\n", (unsigned long) RETVAL));
140 ST(0) = sv_newmortal() ;
142 SaveError("%s",dlerror()) ;
144 sv_setiv( ST(0), (IV)RETVAL);
153 # These functions should not need changing on any platform:
156 dl_install_xsub(perl_name, symref, filename="$Package")
161 DLDEBUG(2,PerlIO_printf(PerlIO_stderr(), "dl_install_xsub(name=%s, symref=%lx)\n",
162 perl_name, (unsigned long) symref));
163 ST(0)=sv_2mortal(newRV((SV*)newXS(perl_name, (void(*)(CV *))symref, filename)));