home *** CD-ROM | disk | FTP | other *** search
-
- <HTML>
- <HEAD>
- <TITLE>DynaLoader - Dynamically load C libraries into Perl code</TITLE>
- <LINK REL="stylesheet" HREF="../Active.css" TYPE="text/css">
- <LINK REV="made" HREF="mailto:">
- </HEAD>
-
- <BODY>
- <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
- <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
- <STRONG><P CLASS=block> DynaLoader - Dynamically load C libraries into Perl code</P></STRONG>
- </TD></TR>
- </TABLE>
-
- <A NAME="__index__"></A>
- <!-- INDEX BEGIN -->
-
- <UL>
-
- <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
-
- <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
- <LI><A HREF="#description">DESCRIPTION</A></LI>
- <LI><A HREF="#author">AUTHOR</A></LI>
- </UL>
- <!-- INDEX END -->
-
- <HR>
- <P>
- <H1><A NAME="name">NAME</A></H1>
- <P>DynaLoader - Dynamically load C libraries into Perl code</P>
- <P>dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_unload_file(), dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(), dl_install_xsub(), dl_load_flags(), <A HREF="#item_bootstrap"><CODE>bootstrap()</CODE></A> - routines used by DynaLoader modules</P>
- <P>
- <HR>
- <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
- <UL>
- <LI>Linux</LI>
- <LI>Solaris</LI>
- <LI>Windows</LI>
- </UL>
- <HR>
- <H1><A NAME="synopsis">SYNOPSIS</A></H1>
- <PRE>
- package YourPackage;
- require DynaLoader;
- @ISA = qw(... DynaLoader ...);
- bootstrap YourPackage;</PRE>
- <PRE>
- # optional method for 'global' loading
- sub dl_load_flags { 0x01 }</PRE>
- <P>
- <HR>
- <H1><A NAME="description">DESCRIPTION</A></H1>
- <P>This document defines a standard generic interface to the dynamic
- linking mechanisms available on many platforms. Its primary purpose is
- to implement automatic dynamic loading of Perl modules.</P>
- <P>This document serves as both a specification for anyone wishing to
- implement the DynaLoader for a new platform and as a guide for
- anyone wishing to use the DynaLoader directly in an application.</P>
- <P>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 and other platforms.</P>
- <P>It is also hoped that the interface will cover the needs of OS/2, NT
- etc and also allow pseudo-dynamic linking (using <CODE>ld -A</CODE> at runtime).</P>
- <P>It must be stressed that the DynaLoader, by itself, 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 arguments. A C::DynaLib module
- is available from CPAN sites which performs that function for some
- common system types.</P>
- <P>DynaLoader Interface Summary</P>
- <PRE>
- @dl_library_path
- @dl_resolve_using
- @dl_require_symbols
- $dl_debug
- @dl_librefs
- @dl_modules
- Implemented in:
- bootstrap($modulename) Perl
- @filepaths = dl_findfile(@names) Perl
- $flags = $modulename->dl_load_flags Perl
- $symref = dl_find_symbol_anywhere($symbol) Perl</PRE>
- <PRE>
- $libref = dl_load_file($filename, $flags) C
- $status = dl_unload_file($libref) C
- $symref = dl_find_symbol($libref, $symbol) C
- @symbols = dl_undef_symbols() C
- dl_install_xsub($name, $symref [, $filename]) C
- $message = dl_error C</PRE>
- <DL>
- <DT><STRONG><A NAME="item_%40dl_library_path">@dl_library_path</A></STRONG><BR>
- <DD>
- The standard/default list of directories in which <A HREF="#item_dl_findfile"><CODE>dl_findfile()</CODE></A> will
- search for libraries etc. Directories are searched in order:
- $dl_library_path[0], [1], ... etc
- <P>@dl_library_path is initialised to hold the list of 'normal' directories
- (<EM>/usr/lib</EM>, etc) determined by <STRONG>Configure</STRONG> (<CODE>$Config{'libpth'}</CODE>). This should
- ensure portability across a wide range of platforms.</P>
- <P>@dl_library_path should also be initialised with any other directories
- that can be determined from the environment at runtime (such as
- LD_LIBRARY_PATH for SunOS).</P>
- <P>After initialisation @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 libraries with the same name
- in the 'normal' directories.</P>
- <P>The load function that <A HREF="#item_dl_load_file"><CODE>dl_load_file()</CODE></A> calls may require an absolute
- pathname. The <A HREF="#item_dl_findfile"><CODE>dl_findfile()</CODE></A> 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.</P>
- <P></P>
- <DT><STRONG><A NAME="item_%40dl_resolve_using">@dl_resolve_using</A></STRONG><BR>
- <DD>
- A list of additional libraries or other shared objects which can be
- used to resolve any undefined symbols that might be generated by a
- later call to load_file().
- <P>This is only required on some platforms which do not handle dependent
- libraries automatically. For example the Socket Perl extension
- library (<EM>auto/Socket/Socket.so</EM>) contains references to many socket
- functions which need to be resolved when it's loaded. Most platforms
- will automatically know where to find the 'dependent' library (e.g.,
- <EM>/usr/lib/libsocket.so</EM>). A few platforms need to be told the
- location of the dependent library explicitly. Use @dl_resolve_using
- for this.</P>
- <P>Example usage:</P>
- <PRE>
- @dl_resolve_using = dl_findfile('-lsocket');</PRE>
- <P></P>
- <DT><STRONG><A NAME="item_%40dl_require_symbols">@dl_require_symbols</A></STRONG><BR>
- <DD>
- 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.
- <P></P>
- <DT><STRONG><A NAME="item_%40dl_librefs">@dl_librefs</A></STRONG><BR>
- <DD>
- An array of the handles returned by successful calls to dl_load_file(),
- made by bootstrap, in the order in which they were loaded.
- Can be used with <A HREF="#item_dl_find_symbol"><CODE>dl_find_symbol()</CODE></A> to look for a symbol in any of
- the loaded files.
- <P></P>
- <DT><STRONG><A NAME="item_%40dl_modules">@dl_modules</A></STRONG><BR>
- <DD>
- An array of module (package) names that have been bootstrap'ed.
- <P></P>
- <DT><STRONG><A NAME="item_dl_error"><CODE>dl_error()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $message = dl_error();</PRE>
- <P>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.</P>
- <P>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 (e.g., dlerror()).</P>
- <P></P>
- <DT><STRONG><A NAME="item_%24dl_debug">$dl_debug</A></STRONG><BR>
- <DD>
- 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.
- <P>$dl_debug is set to <CODE>$ENV{'PERL_DL_DEBUG'}</CODE> if defined.</P>
- <P>For the DynaLoader developer/porter there is a similar debugging
- variable added to the C code (see dlutils.c) and enabled if Perl was
- built with the <STRONG>-DDEBUGGING</STRONG> flag. This can also be set via the
- PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
- higher for more.</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_findfile"><CODE>dl_findfile()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- @filepaths = dl_findfile(@names)</PRE>
- <P>Determine 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.</P>
- <P>Names can be specified in a variety of platform independent forms. Any
- names in the form <STRONG>-lname</STRONG> are converted into <EM>libname.*</EM>, where <EM>.*</EM> is
- an appropriate suffix for the platform.</P>
- <P>If a name does not already have a suitable prefix and/or suffix then
- the corresponding file will be searched for by trying combinations of
- prefix and suffix appropriate to the platform: ``$name.o'', ``lib$name.*''
- and ``$name''.</P>
- <P>If any directories are included in @names they are searched before
- @dl_library_path. Directories may be specified as <STRONG>-Ldir</STRONG>. Any other
- names are treated as filenames to be searched for.</P>
- <P>Using arguments of the form <CODE>-Ldir</CODE> and <CODE>-lname</CODE> is recommended.</P>
- <P>Example:</P>
- <PRE>
- @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));</PRE>
- <P></P>
- <DT><STRONG><A NAME="item_dl_expandspec"><CODE>dl_expandspec()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $filepath = dl_expandspec($spec)</PRE>
- <P>Some unusual systems, such as VMS, require special filename handling in
- order to deal with symbolic names for files (i.e., VMS's Logical Names).</P>
- <P>To support these systems a <A HREF="#item_dl_expandspec"><CODE>dl_expandspec()</CODE></A> function can be implemented
- either in the <EM>dl_*.xs</EM> file or code can be added to the autoloadable
- <A HREF="#item_dl_expandspec"><CODE>dl_expandspec()</CODE></A> function in <EM>DynaLoader.pm</EM>. See <EM>DynaLoader.pm</EM> for
- more information.</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_load_file"><CODE>dl_load_file()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $libref = dl_load_file($filename, $flags)</PRE>
- <P>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. Returns undef on error.</P>
- <P>The $flags argument to alters dl_load_file behaviour.
- Assigned bits:</P>
- <PRE>
- 0x01 make symbols available for linking later dl_load_file's.
- (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
- (ignored under VMS; this is a normal part of image linking)</PRE>
- <P>(On systems that provide a handle for the loaded object such as SunOS
- and HPUX, $libref will be that handle. 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.)</P>
- <P>This is the function that does the real work. It should use the
- current values of @dl_require_symbols and @dl_resolve_using if required.</P>
- <PRE>
- 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])</PRE>
- <P>(The <CODE>dlopen()</CODE> function is also used by Solaris and some versions of
- Linux, and is a common choice when providing a ``wrapper'' on other
- mechanisms as is done in the OS/2 port.)</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_unload_file"><CODE>dl_unload_file()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $status = dl_unload_file($libref)</PRE>
- <P>Dynamically unload $libref, which must be an opaque 'library reference' as
- returned from dl_load_file. Returns one on success and zero on failure.</P>
- <P>This function is optional and may not necessarily be provided on all platforms.
- If it is defined, it is called automatically when the interpreter exits for
- every shared object or library loaded by DynaLoader::bootstrap. All such
- library references are stored in @dl_librefs by DynaLoader::Bootstrap as it
- loads the libraries. The files are unloaded in last-in, first-out order.</P>
- <P>This unloading is usually necessary when embedding a shared-object perl (e.g.
- one configured with -Duseshrplib) within a larger application, and the perl
- interpreter is created and destroyed several times within the lifetime of the
- application. In this case it is possible that the system dynamic linker will
- unload and then subsequently reload the shared libperl without relocating any
- references to it from any files DynaLoaded by the previous incarnation of the
- interpreter. As a result, any shared objects opened by DynaLoader may point to
- a now invalid 'ghost' of the libperl shared object, causing apparently random
- memory corruption and crashes. This behaviour is most commonly seen when using
- Apache and mod_perl built with the APXS mechanism.</P>
- <PRE>
- SunOS: dlclose($libref)
- HP-UX: ???
- Linux: ???
- NeXT: ???
- VMS: ???</PRE>
- <P>(The <CODE>dlclose()</CODE> function is also used by Solaris and some versions of
- Linux, and is a common choice when providing a ``wrapper'' on other
- mechanisms as is done in the OS/2 port.)</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_loadflags"><CODE>dl_loadflags()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $flags = dl_loadflags $modulename;</PRE>
- <P>Designed to be a method call, and to be overridden by a derived class
- (i.e. a class which has DynaLoader in its @ISA). The definition in
- DynaLoader itself returns 0, which produces standard behavior from
- dl_load_file().</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_find_symbol"><CODE>dl_find_symbol()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $symref = dl_find_symbol($libref, $symbol)</PRE>
- <P>Return the address of the symbol $symbol or <A HREF="../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if not found. If the
- target system has separate functions to search for symbols of different
- types then <A HREF="#item_dl_find_symbol"><CODE>dl_find_symbol()</CODE></A> should search for function symbols first and
- then other types.</P>
- <P>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().</P>
- <PRE>
- 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)</PRE>
- <P></P>
- <DT><STRONG><A NAME="item_dl_find_symbol_anywhere"><CODE>dl_find_symbol_anywhere()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- $symref = dl_find_symbol_anywhere($symbol)</PRE>
- <P>Applies <A HREF="#item_dl_find_symbol"><CODE>dl_find_symbol()</CODE></A> to the members of @dl_librefs and returns
- the first match found.</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_undef_symbols"><CODE>dl_undef_symbols()</CODE></A></STRONG><BR>
- <DD>
- Example
- <PRE>
- @symbols = dl_undef_symbols()</PRE>
- <P>Return a list of symbol names which remain undefined after load_file().
- Returns <CODE>()</CODE> if not known. Don't worry if your platform does not provide
- a mechanism for this. Most do not need it and hence do not provide it,
- they just return an empty list.</P>
- <P></P>
- <DT><STRONG><A NAME="item_dl_install_xsub"><CODE>dl_install_xsub()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <PRE>
- dl_install_xsub($perl_name, $symref [, $filename])</PRE>
- <P>Create a new Perl external subroutine named $perl_name using $symref as
- a pointer to the function which implements the routine. This is simply
- a direct call to newXSUB(). Returns a reference to the installed
- function.</P>
- <P>The $filename parameter is used by Perl to identify the source file for
- the function if required by die(), <A HREF="../lib/Pod/perlfunc.html#item_caller"><CODE>caller()</CODE></A> or the debugger. If
- $filename is not defined then ``DynaLoader'' will be used.</P>
- <P></P>
- <DT><STRONG><A NAME="item_bootstrap"><CODE>bootstrap()</CODE></A></STRONG><BR>
- <DD>
- Syntax:
- <P><A HREF="#item_bootstrap"><CODE>bootstrap($module)</CODE></A></P>
- <P>This is the normal entry point for automatic dynamic loading in Perl.</P>
- <P>It performs the following actions:</P>
- <UL>
- <LI>
- locates an auto/$module directory by searching @INC
- <P></P>
- <LI>
- uses <A HREF="#item_dl_findfile"><CODE>dl_findfile()</CODE></A> to determine the filename to load
- <P></P>
- <LI>
- sets @dl_require_symbols to <CODE>("boot_$module")</CODE>
- <P></P>
- <LI>
- executes an <EM>auto/$module/$module.bs</EM> file if it exists
- (typically used to add to @dl_resolve_using any files which
- are required to load the module on the current platform)
- <P></P>
- <LI>
- calls <CODE>dl_load_flags()</CODE> to determine how to load the file.
- <P></P>
- <LI>
- calls <A HREF="#item_dl_load_file"><CODE>dl_load_file()</CODE></A> to load the file
- <P></P>
- <LI>
- calls <A HREF="#item_dl_undef_symbols"><CODE>dl_undef_symbols()</CODE></A> and warns if any symbols are undefined
- <P></P>
- <LI>
- calls <A HREF="#item_dl_find_symbol"><CODE>dl_find_symbol()</CODE></A> for ``boot_$module''
- <P></P>
- <LI>
- calls <A HREF="#item_dl_install_xsub"><CODE>dl_install_xsub()</CODE></A> to install it as ``${module}::bootstrap''
- <P></P>
- <LI>
- calls &{``${module}::bootstrap''} to bootstrap the module (actually
- it uses the function reference returned by dl_install_xsub for speed)
- <P></P></UL>
- </DL>
- <P>
- <HR>
- <H1><A NAME="author">AUTHOR</A></H1>
- <P>Tim Bunce, 11 August 1994.</P>
- <P>This interface is based on the work and comments of (in no particular
- order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
- Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.</P>
- <P>Larry Wall designed the elegant inherited bootstrap mechanism and
- implemented the first Perl 5 dynamic loader using it.</P>
- <P>Solaris global loading added by Nick Ing-Simmons with design/coding
- assistance from Tim Bunce, January 1996.</P>
- <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
- <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
- <STRONG><P CLASS=block> DynaLoader - Dynamically load C libraries into Perl code</P></STRONG>
- </TD></TR>
- </TABLE>
-
- </BODY>
-
- </HTML>
-