|
Chapter 7 The Standard Perl Library |
|
package YourModule; require DynaLoader; @ISA = qw(... DynaLoader ...); bootstrap YourModule;
This module defines the standard Perl interface to the dynamic linking mechanisms available on many platforms. A common theme throughout the module system is that
using
a module should be easy, even if the module itself (or the installation of the module) is more complicated as a result. This applies particularly to the DynaLoader. To use it in your own module, all you need are the incantations listed above in the synopsis. This will work whether YourModule is statically or dynamically linked into Perl. (This is a
Configure
option for each module.) The
bootstrap()
method will either call YourModule's bootstrap routine directly if YourModule is statically linked into Perl, or if not, YourModule will inherit the
bootstrap()
method from DynaLoader, which will do everything necessary to load in your module, and then call YourModule's
bootstrap()
method for you, as if it were there all the time and you called it yourself. Piece of cake, of the have-it-and-eat-it-too variety.
The rest of this description talks about the DynaLoader from the viewpoint of someone who wants to extend the DynaLoader module to a new architecture. The Configure process selects which kind of dynamic loading to use by choosing to link in one of several C implementations, which must be linked into perl statically. (This is unlike other C extensions, which provide a single implementation, which may be linked in either statically or dynamically.)
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, Win-32, and other platforms. By itself, though, DynaLoader 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 its arguments in any sort of portable form. This job is delegated to the other extension modules that you may load in by using DynaLoader.
Variables:
@dl_library_path @dl_resolve_using @dl_require_symbols $dl_debug
Subroutines:
bootstrap($modulename); @filepaths = dl_findfile(@names); $filepath = dl_expandspec($spec); $libref = dl_load_file($filename); $symref = dl_find_symbol($libref, $symbol); @symbols = dl_undef_symbols(); dl_install_xsub($name, $symref [, $filename]); $message = dl_error;
The
bootstrap()
and
dl_findfile()
routines are standard across all platforms, and so are defined in
DynaLoader.pm
. The rest of the functions are supplied by the particular
.xs
file that supplies the implementation for the platform. (You can examine the existing implementations in the
ext/DynaLoader/
*
.xs
files in the Perl source directory. You should also read
DynaLoader.pm
, of course.) These implementations may also tweak the default values of the variables listed below.
@dl_library_path
The default list of directories in which
dl_findfile()
will search for libraries. Directories are searched in the order they are given in this array variable, beginning with subscript 0.
@dl_library_path
is initialized to hold the list of "normal" directories (
/usr/lib
and so on) determined by the Perl installation script,
Configure
, and given by
$Config{'libpth'}
. This is to ensure portability across a wide range of platforms.
@dl_library_path
should also be initialized with any other directories that can be determined from the environment at run-time (such as
LD_LIBRARY_PATH
for SunOS). After initialization,
@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 standard libraries with the same name. The load function that
dl_load_file()
calls might 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 that can be used to resolve any undefined symbols that might be generated by a later call to
dl_load_file()
. This is only required on some platforms that do not handle dependent libraries automatically. For example, the Socket extension shared library (
auto/Socket/Socket.so
) contains references to many socket functions that need to be resolved when it's loaded. Most platforms will automatically know where to find the "dependent" library (for example,
/usr/lib/libsocket.so
). A few platforms need to be told the location of the dependent library explicitly. Use
@dl_resolve_using
for this. Example:
@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.
dl_error
$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 (see, for example,
dlerror
(3)).
$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 and porter there is a similar debugging variable added to the C code (see
dlutils.c
) and enabled if Perl was built 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.
dl_findfile
@filepaths = dl_findfile(@names)
Determines 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 or suffix, then the corresponding file will be sought by trying prefix and suffix combinations 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));
dl_expandspec
$filepath = dl_expandspec($spec)
Some unusual systems such as VMS require special filename handling in order to deal with symbolic names for files (that is, 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
.
dl_load_file
$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.
dl_load_file()
returns the undefined value on error. (On systems that provide a handle for the loaded object such as SunOS and HP-UX, the returned handle will be
$libref
. 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.) Below are some of the functions that do the real work. Such functions 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])
dl_find_symbol
$symref = dl_find_symbol($libref, $symbol)
Returns the address of the symbol
$symbol
, or the undefined value 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 search for 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()
. Here are some current implementations:
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)
dl_undef_symbols
@symbols = dl_undef_symbols()
Returns a list of symbol names which remain undefined after
dl_load_file()
. It returns
()
if these names are not known. Don't worry if your platform does not provide a mechanism for this. Most platforms do not need it and hence do not provide it; they just return an empty list.
dl_install_xsub
dl_install_xsub($perl_name, $symref [, $filename])
Creates a new Perl external subroutine named
$perl_name
using
$symref
as a pointer to the function that implements the routine. This is simply a direct call to
newXSUB()
. It 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()
bootstrap($module);
This is the normal entry point for automatic dynamic loading in Perl.
It performs the following actions:
Locates an
auto/$module
directory by searching
@INC
Uses
dl_findfile()
to determine the filename to load
Sets
@dl_require_symbols
to
("boot_$module")
Executes an
auto/$module/$module.bs
file if it exists (typically used to add to
@dl_resolve_using
any files that are required to load the module on the current platform)
Calls
dl_load_file()
to load the file
Calls
dl_undef_symbols()
and warns if any symbols are undefined
Calls
dl_find_symbol()
for
"boot_$module"
Calls
dl_install_xsub()
to install it as
${module}::bootstrap
Calls
&{"${module}::bootstrap"}
to bootstrap the module (actually it uses the function reference returned by
dl_install_xsub()
for speed)
|
|
|
|
| 7.2.11 DirHandle - Supply Object Methods for Directory Handles |
|
7.2.13 English - Use English or awk Names for Punctuation Variables |