diff options
Diffstat (limited to 'ext/DynaLoader/DynaLoader.doc')
| -rw-r--r-- | ext/DynaLoader/DynaLoader.doc | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/ext/DynaLoader/DynaLoader.doc b/ext/DynaLoader/DynaLoader.doc new file mode 100644 index 0000000000..85d606ff9b --- /dev/null +++ b/ext/DynaLoader/DynaLoader.doc @@ -0,0 +1,257 @@ +======================================================================= +Specification for the Generic Dynamic Linking 'DynaLoader' Module + +This specification defines a standard generic interface to the dynamic +linking mechanisms available on many platforms. Its primary purpose is +to implement automatic dynamic loading of perl modules. + +The DynaLoader is designed to be a very simple high-level +interface that is sufficiently general to cover the requirements +of SunOS, HP-UX, NeXT, Linux, VMS and other platforms. + +It is also hoped that the interface will cover the needs of OS/2, +NT etc and allow pseudo-dynamic linking (using ld -A at runtime). + +This document serves as both a specification for anyone wishing to +implement the DynaLoader for a new platform and as a guide for +anyone wishing to use the DynaLoader directly in an application. + +It must be stressed that the DynaLoader, by itself, is practically +useless for accessing non-perl libraries because it provides almost no +perl-to-C 'glue'. There is, for example, no mechanism for calling a C +library function or supplying arguments. It is anticipated that any +glue that may be developed in the future will be implemented in a +seperate dynamically loaded module. + +This interface is based on the work and comments of (in no particular +order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno +Siegel, Thomas Neumann, Paul Marquess, Charles Bailey and others. + +Larry Wall designed the elegant inherited bootstrap mechanism and +implemented the first perl 5 dynamic loader using it. + +Tim Bunce +11th August 1994 + +---------------------------------------------------------------------- +DynaLoader Interface Summary + + @dl_library_path + @dl_resolve_using + @dl_require_symbols + $dl_debug + Implemented in: + bootstrap($modulename) Perl + @filepaths = dl_findfile(@names) Perl + + $libref = dl_load_file($filename) C + $symref = dl_find_symbol($libref, $symbol) C + @symbols = dl_undef_symbols() C + dl_install_xsub($name, $symref [, $filename]) C + $message = dl_error C + + +---------------------------------------------------------------------- +@dl_library_path + +The standard/default list of directories in which dl_findfile() will +search for libraries etc. Directories are searched in order: +$dl_library_path[0], [1], ... etc + +@dl_library_path is initialised to hold the list of 'normal' directories +(/usr/lib etc) determined by Configure ($Config{'libpth'}). This should +ensure portability across a wide range of platforms. + +@dl_library_path should also be initialised with any other directories +that can be determined from the environment at runtime (such as +LD_LIBRARY_PATH for SunOS). + +After initialisation @dl_library_path can be manipulated by an +application using push and unshift before calling dl_findfile(). +Unshift can be used to add directories to the front of the search order +either to save search time or to override libraries with the same name +in the 'normal' directories. + +The load function that dl_load_file() calls may require an absolute +pathname. The dl_findfile() function and @dl_library_path can be +used to search for and return the absolute pathname for the +library/object that you wish to load. + + +---------------------------------------------------------------------- +@dl_resolve_using + +A list of additional libraries or other shared objects which can be +used to resolve any undefined symbols that might be generated by a +later call to load_file(). + +This is only required on some platforms which do not handle dependent +libraries automatically. For example the Socket perl extension library +(auto/Socket/Socket.so) contains references to many socket functions +which need to be resolved when it's loaded. Most platforms will +automatically know where to find the 'dependent' library (e.g., +/usr/lib/libsocket.so). A few platforms need to to be told the location +of the dependent library explicitly. Use @dl_resolve_using for this. + +Example usage: @dl_resolve_using = dl_findfile('-lsocket'); + + +---------------------------------------------------------------------- +@dl_require_symbols + +A list of one or more symbol names that are in the library/object file +to be dynamically loaded. This is only required on some platforms. + + +---------------------------------------------------------------------- +$message = dl_error + +Error message text from the last failed DynaLoader function. Note +that, similar to errno in unix, a successful function call does not +reset this message. + +Implementations should detect the error as soon as it occurs in any of +the other functions and save the corresponding message for later +retrieval. This will avoid problems on some platforms (such as SunOS) +where the error message is very temporary (e.g., dlerror()). + + +---------------------------------------------------------------------- +$dl_debug + +Internal debugging messages are enabled when $dl_debug is set true. +Currently setting $dl_debug only affects the perl side of the +DynaLoader. These messages should help an application developer to +resolve any DynaLoader usage problems. + +$dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined. + +For the DynaLoader developer/porter there is a similar debugging +variable added to the C code (see dlutils.c) and enabled if perl is +compiled with the -DDEBUGGING flag. This can also be set via the +PERL_DL_DEBUG environment variable. Set to 1 for minimal information or +higher for more. + + +---------------------------------------------------------------------- +@filepaths = dl_findfile(@names) + +Determine the full paths (including file suffix) of one or more +loadable files given their generic names and optionally one or more +directories. Searches directories in @dl_library_path by default and +returns an empty list if no files were found. + +Names can be specified in a variety of platform independent forms. Any +names in the form '-lname' are converted into 'libname.*', where .* is +an appropriate suffix for the platform. + +If a name does not already have a suitable prefix and/or suffix then +the corresponding file will be searched for by trying combinations of +prefix and suffix appropriate to the platform: "$name.o", "lib$name.*" +and "$name". + +If any directories are included in @names they are searched before +@dl_library_path. Directories may be specified as -Ldir. Any other names +are treated as filenames to be searched for. + +Using arguments of the form -Ldir and -lname is recommended. + +Example: @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix)); + + +---------------------------------------------------------------------- +$filepath = dl_expandspec($spec) + +Some unusual systems, such as VMS, require special filename handling in +order to deal with symbolic names for files (i.e., VMS's Logical Names). + +To support these systems a dl_expandspec function can be implemented +either in the dl_*.xs file or code can be added to the autoloadable +dl_expandspec function in DynaLoader.pm. See DynaLoader.pm for more +information. + + + +---------------------------------------------------------------------- +$libref = dl_load_file($filename) + +Dynamically load $filename, which must be the path to a shared object +or library. An opaque 'library reference' is returned as a handle for +the loaded object. Returns undef on error. + +(On systems that provide a handle for the loaded object such as SunOS +and HPUX, $libref will be that handle. On other systems $libref will +typically be $filename or a pointer to a buffer containing $filename. +The application should not examine or alter $libref in any way.) + +This is function that does the real work. It should use the current +values of @dl_require_symbols and @dl_resolve_using if required. + +SunOS: dlopen($filename) +HP-UX: shl_load($filename) +Linux: dld_create_reference(@dl_require_symbols); dld_link($filename) +NeXT: rld_load($filename, @dl_resolve_using) +VMS: lib$find_image_symbol($filename,$dl_require_symbols[0]) + + +---------------------------------------------------------------------- +$symref = dl_find_symbol($libref, $symbol) + +Return the address of the symbol $symbol or undef if not found. If the +target system has separate functions to search for symbols of different +types then dl_find_symbol should search for function symbols first and +then other types. + +The exact manner in which the address is returned in $symref is not +currently defined. The only initial requirement is that $symref can +be passed to, and understood by, dl_install_xsub(). + +SunOS: dlsym($libref, $symbol) +HP-UX: shl_findsym($libref, $symbol) +Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol) +NeXT: rld_lookup("_$symbol") +VMS: lib$find_image_symbol($libref,$symbol) + + +---------------------------------------------------------------------- +@symbols = dl_undef_symbols() + +Return a list of symbol names which remain undefined after load_file(). +Returns () if not known. Don't worry if your platform does not provide +a mechanism for this. Most do not need it and hence do not provide it. + + +---------------------------------------------------------------------- +dl_install_xsub($perl_name, $symref [, $filename]) + +Create a new Perl external subroutine named $perl_name using $symref as +a pointer to the function which implements the routine. This is simply +a direct call to newXSUB(). Returns a reference to the installed +function. + +The $filename parameter is used by Perl to identify the source file for +the function if required by die(), caller() or the debugger. If +$filename is not defined then "DynaLoader" will be used. + + +---------------------------------------------------------------------- +bootstrap($module) + +This is the normal entry point for automatic dynamic loading in Perl. + +It performs the following actions: + 1. locates an auto/$module directory by searching @INC + 2. uses dl_findfile() to determine the filename to load + 3. sets @dl_require_symbols to ("boot_$module") + 4. executes an auto/$module/$^R/$module.bs file if it exists + (typically used to add to @dl_resolve_using any files which + are required to load the module on the current platform) + 5. calls dl_load_file() to load the file + 6. calls dl_undef_symbols() and warns if any symbols are undefined + 7. calls dl_find_symbol() for "boot_$module" + 8. calls dl_install_xsub() to install it as "${module}::bootstrap" + 9. calls &{"${module}::bootstrap"} to bootstrap the module + + +====================================================================== +End. |