Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DynaLoader::Functions(User Contributed Perl DocumentatDynaLoader::Functions(3)

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.32.1			  2021-02-28	      DynaLoader::Functions(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | SEE ALSO | AUTHOR | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DynaLoader::Functions&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help