{ "content": [ { "type": "text", "text": "# DynaLoader::Functions (perldoc)\n\n## NAME\n\nDynaLoader::Functions - deconstructed dynamic C library loading\n\n## SYNOPSIS\n\nuse DynaLoader::Functions qw(\nloadableformodule\nlinkableforloadable linkableformodule);\n$loadable = loadableformodule(\"Acme::Widget\");\n@linkable = linkableforloadable($loadable);\n@linkable = linkableformodule(\"Acme::Widget\");\nuse DynaLoader::Functions qw(dynaload dynaresolve dynaunload);\n$libh = dynaload($loadable, {\nrequiresymbols => [\"bootAcmeWidget\"],\n});\nmy $bootfunc = dynaresolve($libh, \"bootAcmeWidget\");\ndynaunload($libh);\n\n## DESCRIPTION\n\nThis module provides a function-based interface to dynamic loading as used by Perl. Some details\nof dynamic loading are very platform-dependent, so correct use of these functions requires the\nprogrammer to be mindful of the space of platform variations.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **FUNCTIONS** (8 subsections)\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "DynaLoader::Functions", "section": "", "mode": "perldoc", "summary": "DynaLoader::Functions - deconstructed dynamic C library loading", "synopsis": "use DynaLoader::Functions qw(\nloadableformodule\nlinkableforloadable linkableformodule);\n$loadable = loadableformodule(\"Acme::Widget\");\n@linkable = linkableforloadable($loadable);\n@linkable = linkableformodule(\"Acme::Widget\");\nuse DynaLoader::Functions qw(dynaload dynaresolve dynaunload);\n$libh = dynaload($loadable, {\nrequiresymbols => [\"bootAcmeWidget\"],\n});\nmy $bootfunc = dynaresolve($libh, \"bootAcmeWidget\");\ndynaunload($libh);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 16, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [] }, { "name": "FUNCTIONS", "lines": 1, "subsections": [ { "name": "File finding", "lines": 1 }, { "name": "loadable_for_module", "lines": 11 }, { "name": "linkable_for_loadable", "lines": 13 }, { "name": "linkable_for_module", "lines": 9 }, { "name": "Low-level dynamic loading", "lines": 1 }, { "name": "dyna_load", "lines": 46 }, { "name": "dyna_resolve", "lines": 13 }, { "name": "dyna_unload", "lines": 14 } ] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 2, "subsections": [] }, { "name": "LICENSE", "lines": 3, "subsections": [] } ], "sections": { "NAME": { "content": "DynaLoader::Functions - deconstructed dynamic C library loading\n", "subsections": [] }, "SYNOPSIS": { "content": "use DynaLoader::Functions qw(\nloadableformodule\nlinkableforloadable linkableformodule);\n\n$loadable = loadableformodule(\"Acme::Widget\");\n@linkable = linkableforloadable($loadable);\n@linkable = linkableformodule(\"Acme::Widget\");\n\nuse DynaLoader::Functions qw(dynaload dynaresolve dynaunload);\n\n$libh = dynaload($loadable, {\nrequiresymbols => [\"bootAcmeWidget\"],\n});\nmy $bootfunc = dynaresolve($libh, \"bootAcmeWidget\");\ndynaunload($libh);\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides a function-based interface to dynamic loading as used by Perl. Some details\nof dynamic loading are very platform-dependent, so correct use of these functions requires the\nprogrammer to be mindful of the space of platform variations.\n", "subsections": [] }, "FUNCTIONS": { "content": "", "subsections": [ { "name": "File finding", "content": "" }, { "name": "loadable_for_module", "content": "*MODULENAME* must be the name of a Perl module, in bareword syntax with \"::\" separators.\nThe named module is presumed to be an XS extension following standard conventions, and its\nruntime-loadable C library file is searched for. If found, the name of the library file is\nreturned. If it cannot be found, the function \"die\"s with an informative error message.\n\nIf the named module is actually not an XS extension, or is not installed, or stores its C\nlibrary in a non-standard place, there is a non-trivial danger that this function will find\nsome other library file and believe it to be the right one. This function should therefore\nonly be used when there is an expectation that the module is installed and would in normal\noperation load its corresponding C library.\n" }, { "name": "linkable_for_loadable", "content": "If symbols in one runtime-loadable C library are to be made available to another\nruntime-loadable C library, depending on the platform it may be necessary to refer to the\nexporting library when linking the importing library. Generally this is not required on\nUnix, but it is required on Windows. Where it is required to refer to the exporting library\nat link time, the file used may be the loadable library file itself, or may be a separate\nfile used only for this purpose. Given the loadable form of an exporting library, this\nfunction determines what is required at link time for an importing library.\n\n*LOADABLEFILENAME* must be the name of a runtime-loadable C library file. The function\nchecks what is required to link a library that will at runtime import symbols from this\nlibrary. It returns a list (which will be empty on many platforms) of names of files that\nmust be used as additional objects when linking the importing library.\n" }, { "name": "linkable_for_module", "content": "Performs the job of \"linkableforloadable\" (which see for explanation), but based on a\nmodule name instead of a loadable library filename.\n\n*MODULENAME* must be the name of a Perl module, in bareword syntax with \"::\" separators.\nThe function checks what is required to link a library that will at runtime import symbols\nfrom the loadable C library associated with the module. It returns a list (which will be\nempty on many platforms) of names of files that must be used as additional objects when\nlinking the importing library.\n" }, { "name": "Low-level dynamic loading", "content": "" }, { "name": "dyna_load", "content": "Dynamically load the runtime-loadable C library in the file named *LOADABLEFILENAME*. The\nprocess is influenced by optional information supplied in the hash referenced by *OPTIONS*.\nOn the platforms that make dynamic loading easiest it is not necessary to supply any options\n(in which case the parameter may be omitted), but if wide portability is required then some\noptions are required. The permitted keys in the *OPTIONS* hash are:\n\nresolveusing\nReference to an array, default empty, of names of additional library files required to\nsupply symbols used by the library being loaded. On most platforms this is not used. On\nthose platforms where it is required, the need for this will be known by whatever\ngenerated the library to be loaded, and it will normally be set by a bootstrap file (see\nusebootstrapoptions below).\n\nrequiresymbols\nReference to an array, default empty, of names of symbols expected to be found in the\nlibrary being loaded. On most platforms this is not used, but on some a library cannot\nbe loaded without naming at least one symbol for which a need can be satisfied by the\nlibrary.\n\nusebootstrapoptions\nTruth value, default false, controlling whether a \"bootstrap\" file will be consulted as\nan additional source of options to control loading. The \"bootstrap\" file, if it exists,\nis located in the same directory as the loadable library file, and has a similar name\ndiffering only in its \".bs\" ending.\n\nsymbolsglobal\nTruth value, default false, indicating whether symbols found in the library being loaded\nmust be made available to subsequently-loaded libraries. Depending on platform, symbols\nmay be so available even if it is not requested. Some platforms, on the other hand,\ncan't provide this facility.\n\nOn platforms incapable of making loaded symbols globally available, currently loading is\nliable to claim success while leaving the symbols de facto unavailable. It is intended\nthat in the future such platforms will instead generate an exception when this facility\nis requested.\n\nunresolvedaction\nString keyword indicating what should be done if unresolved symbols are detected while\nloading the library. It may be \"ERROR\" (default) to treat it as an error, \"WARN\" to emit\na warning, or \"IGNORE\" to ignore the situation. Some platforms can't detect this\nproblem, so passing this check doesn't guarantee that there won't be any runtime\nproblems due to unresolved symbols.\n\nOn success, returns a handle that can be used to refer to the loaded library for subsequent\ncalls to \"dynaresolve\" and \"dynaunload\". On failure, \"die\"s.\n" }, { "name": "dyna_resolve", "content": "Resolve the symbol *SYMBOL* in the previously-loaded library identified by the\n*LIBRARYHANDLE*. The process is influenced by optional information supplied in the hash\nreferenced by *OPTIONS*. The permitted keys in the *OPTIONS* hash are:\n\nunresolvedaction\nString keyword indicating what should be done if the symbol cannot be resolved. It may\nbe \"ERROR\" (default) to treat it as an error, \"WARN\" to emit a warning and return\n\"undef\", or \"IGNORE\" to return \"undef\" without a warning.\n\nOn success, returns the value of the specified symbol, in a platform-dependent format.\nReturns \"undef\" if the symbol could not be resolved and this is not being treated as an\nerror.\n" }, { "name": "dyna_unload", "content": "Unload the previously-loaded library identified by the *LIBRARYHANDLE*. The process is\ninfluenced by optional information supplied in the hash referenced by *OPTIONS*. The\npermitted keys in the *OPTIONS* hash are:\n\nfailaction\nString keyword indicating what should be done if unloading detectably fails. It may be\n\"ERROR\" (default) to treat it as an error, \"WARN\" to emit a warning, or \"IGNORE\" to\nignore the situation.\n\nOn some platforms unloading is not possible. On any platform, unloading can be expected to\ncause mayhem if any code from the library is currently executing, if there are any live\nreferences to data in the library, or if any symbols provided by the library are referenced\nby any subsequently-loaded library.\n" } ] }, "SEE ALSO": { "content": "DynaLoader, ExtUtils::CBuilder, XSLoader\n", "subsections": [] }, "AUTHOR": { "content": "Andrew Main (Zefram) \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 2011, 2012, 2013, 2017 Andrew Main (Zefram) \n", "subsections": [] }, "LICENSE": { "content": "This module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } } } }