DynaLoader::Functions - phpMan

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 AT fysh.org>

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

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