Provided by: libdynaloader-functions-perl_0.003-3_all bug

NAME

       DynaLoader::Functions - deconstructed dynamic C library loading

SYNOPSIS

           use DynaLoader::Functions qw(
               loadable_for_module
               linkable_for_loadable linkable_for_module);

           $loadable = loadable_for_module("Acme::Widget");
           @linkable = linkable_for_loadable($loadable);
           @linkable = linkable_for_module("Acme::Widget");

           use DynaLoader::Functions qw(dyna_load dyna_resolve dyna_unload);

           $libh = dyna_load($loadable, {
                       require_symbols => ["boot_Acme__Widget"],
                   });
           my $bootfunc = dyna_resolve($libh, "boot_Acme__Widget");
           dyna_unload($libh);

DESCRIPTION

       This module provides a function-based interface to dynamic loading as used by Perl.  Some details of
       dynamic loading are very platform-dependent, so correct use of these functions requires the programmer to
       be mindful of the space of platform variations.

FUNCTIONS

   File finding
       loadable_for_module(MODULE_NAME)
           MODULE_NAME  must  be  the name of a Perl module, in bareword syntax with "::" separators.  The named
           module is presumed to be an XS extension following standard conventions, and its  runtime-loadable  C
           library  file  is searched for.  If found, the name of the library file is returned.  If it cannot be
           found, the function "die"s with an informative error message.

           If the named module is actually not an XS extension, or is not installed, or stores its C library  in
           a  non-standard  place, there is a non-trivial danger that this function will find some other library
           file and believe it to be the right one.  This function should therefore only be used when  there  is
           an  expectation  that  the module is installed and would in normal operation load its corresponding C
           library.

       linkable_for_loadable(LOADABLE_FILENAME)
           If symbols in one runtime-loadable C library are to be made available to another  runtime-loadable  C
           library, depending on the platform it may be necessary to refer to the exporting library when linking
           the importing library.  Generally this is not required on Unix, but it is required on Windows.  Where
           it  is  required  to  refer  to the exporting library at link time, the file used may be the loadable
           library file itself, or may be a separate file used only for this purpose.  Given the  loadable  form
           of  an  exporting  library,  this  function determines what is required at link time for an importing
           library.

           LOADABLE_FILENAME must be the name of a runtime-loadable C library file.  The function checks what is
           required to link a library that will at runtime import symbols from this library.  It returns a  list
           (which  will  be  empty  on many platforms) of names of files that must be used as additional objects
           when linking the importing library.

       linkable_for_module(MODULE_NAME)
           Performs the job of "linkable_for_loadable" (which see for explanation), but based on a  module  name
           instead of a loadable library filename.

           MODULE_NAME must be the name of a Perl module, in bareword syntax with "::" separators.  The function
           checks  what  is  required  to link a library that will at runtime import symbols from the loadable C
           library associated with the module.  It returns a list (which will be empty  on  many  platforms)  of
           names of files that must be used as additional objects when linking the importing library.

   Low-level dynamic loading
       dyna_load(LOADABLE_FILENAME[, OPTIONS])
           Dynamically  load the runtime-loadable C library in the file named LOADABLE_FILENAME.  The process is
           influenced by optional information supplied in the hash referenced by OPTIONS.  On the platforms that
           make dynamic loading easiest it is not necessary to supply any options (in which case  the  parameter
           may  be  omitted), but if wide portability is required then some options are required.  The permitted
           keys in the OPTIONS hash are:

           resolve_using
               Reference to an array, default empty, of names of additional library  files  required  to  supply
               symbols  used  by  the  library  being  loaded.   On  most  platforms this is not used.  On those
               platforms where it is required, the need for this will be known by whatever generated the library
               to be loaded, and it will normally be set by a bootstrap file (see use_bootstrap_options below).

           require_symbols
               Reference to an array, default empty, of names of symbols expected to be  found  in  the  library
               being loaded.  On most platforms this is not used, but on some a library cannot be loaded without
               naming at least one symbol for which a need can be satisfied by the library.

           use_bootstrap_options
               Truth  value,  default  false,  controlling  whether  a  "bootstrap" file will be consulted as an
               additional source of options to control loading.  The "bootstrap" file, if it exists, is  located
               in  the same directory as the loadable library file, and has a similar name differing only in its
               ".bs" ending.

           symbols_global
               Truth value, default false, indicating whether symbols found in the library being loaded must  be
               made  available  to  subsequently-loaded  libraries.   Depending  on  platform, symbols may be so
               available even if it is not requested.  Some platforms, on the other  hand,  can't  provide  this
               facility.

               On  platforms  incapable of making loaded symbols globally available, currently loading is liable
               to claim success while leaving the symbols de facto unavailable.  It  is  intended  that  in  the
               future such platforms will instead generate an exception when this facility is requested.

           unresolved_action
               String  keyword  indicating  what should be done if unresolved symbols are detected while loading
               the library.  It may be "ERROR" (default) to treat it as an error, "WARN" to emit a  warning,  or
               "IGNORE"  to  ignore  the  situation.   Some platforms can't detect this problem, so passing this
               check doesn't guarantee that there won't be any runtime problems due to unresolved symbols.

           On success, returns a handle that can be used to refer to the loaded library for subsequent calls  to
           "dyna_resolve" and "dyna_unload".  On failure, "die"s.

       dyna_resolve(LIBRARY_HANDLE, SYMBOL_NAME[, OPTIONS])
           Resolve  the  symbol  SYMBOL  in the previously-loaded library identified by the LIBRARY_HANDLE.  The
           process is influenced by optional information supplied  in  the  hash  referenced  by  OPTIONS.   The
           permitted keys in the OPTIONS hash are:

           unresolved_action
               String  keyword  indicating  what  should  be  done  if the symbol cannot be resolved.  It may be
               "ERROR" (default) to treat it as an error, "WARN" to  emit  a  warning  and  return  "undef",  or
               "IGNORE" to return "undef" without a warning.

           On  success,  returns  the  value  of  the specified symbol, in a platform-dependent format.  Returns
           "undef" if the symbol could not be resolved and this is not being treated as an error.

       dyna_unload(LIBRARY_HANDLE[, OPTIONS])
           Unload the previously-loaded library identified by the LIBRARY_HANDLE.  The process is influenced  by
           optional  information  supplied in the hash referenced by OPTIONS.  The permitted keys in the OPTIONS
           hash are:

           fail_action
               String keyword indicating what should be done if unloading detectably fails.  It may  be  "ERROR"
               (default) to treat it as an error, "WARN" to emit a warning, or "IGNORE" to ignore the situation.

           On  some  platforms  unloading  is not possible.  On any platform, unloading can be expected to cause
           mayhem if any code from the library is currently executing, if there are any live references to  data
           in  the  library, or if any symbols provided by the library are referenced by any subsequently-loaded
           library.

SEE ALSO

       DynaLoader, ExtUtils::CBuilder, XSLoader

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2011, 2012, 2013, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

       This module is free software; you can redistribute it and/or modify it  under  the  same  terms  as  Perl
       itself.

perl v5.36.0                                       2022-10-13                         DynaLoader::Functions(3pm)