<h2>Editing File: /usr/share/perl5/XSLoader.pm</h2><form method='post'><textarea name='content' class='file-edit'># Generated from XSLoader_pm.PL (resolved %Config::Config value)
# This file is unique for every OS

package XSLoader;

$VERSION = &quot;0.27&quot;;

#use strict;

package DynaLoader;

# No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
# NOTE: All dl_*.xs (including dl_none.xs) define a dl_error() XSUB
boot_DynaLoader('DynaLoader') if defined(&amp;boot_DynaLoader) &amp;&amp;
                                !defined(&amp;dl_error);
package XSLoader;

sub load {
    package DynaLoader;

    my ($caller, $modlibname) = caller();
    my $module = $caller;

    if (@_) {
        $module = $_[0];
    } else {
        $_[0] = $module;
    }

    # work with static linking too
    my $boots = &quot;$module\::bootstrap&quot;;
    goto &amp;$boots if defined &amp;$boots;

    goto \&amp;XSLoader::bootstrap_inherit unless $module and defined &amp;dl_load_file;

    my @modparts = split(/::/,$module);
    my $modfname = $modparts[-1];

    my $modpname = join('/',@modparts);
    my $c = () = split(/::/,$caller,-1);
    $modlibname =~ s,[\\/][^\\/]+$,, while $c--;    # Q&amp;D basename
    # Does this look like a relative path?
    if ($modlibname !~ m{^/}) {
        # Someone may have a #line directive that changes the file name, or
        # may be calling XSLoader::load from inside a string eval.  We cer-
        # tainly do not want to go loading some code that is not in @INC,
        # as it could be untrusted.
        #
        # We could just fall back to DynaLoader here, but then the rest of
        # this function would go untested in the perl core, since all @INC
        # paths are relative during testing.  That would be a time bomb
        # waiting to happen, since bugs could be introduced into the code.
        #
        # So look through @INC to see if $modlibname is in it.  A rela-
        # tive $modlibname is not a common occurrence, so this block is
        # not hot code.
        FOUND: {
            for (@INC) {
                if ($_ eq $modlibname) {
                    last FOUND;
                }
            }
            # Not found.  Fall back to DynaLoader.
            goto \&amp;XSLoader::bootstrap_inherit;
        }
    }
    my $file = &quot;$modlibname/auto/$modpname/$modfname.so&quot;;

#   print STDERR &quot;XSLoader::load for $module ($file)\n&quot; if $dl_debug;

    my $bs = $file;
    $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library

    if (-s $bs) { # only read file if it's not empty
#       print STDERR &quot;BS: $bs ($^O, $dlsrc)\n&quot; if $dl_debug;
        eval { local @INC = ('.'); do $bs; };
        warn &quot;$bs: $@\n&quot; if $@;
	goto \&amp;XSLoader::bootstrap_inherit;
    }

    goto \&amp;XSLoader::bootstrap_inherit if not -f $file;

    my $bootname = &quot;boot_$module&quot;;
    $bootname =~ s/\W/_/g;
    @DynaLoader::dl_require_symbols = ($bootname);

    my $boot_symbol_ref;

    # Many dynamic extension loading problems will appear to come from
    # this section of code: XYZ failed at line 123 of DynaLoader.pm.
    # Often these errors are actually occurring in the initialisation
    # C code of the extension XS file. Perl reports the error as being
    # in this perl code simply because this was the last perl code
    # it executed.

    my $libref = dl_load_file($file, 0) or do { 
        require Carp;
        Carp::croak(&quot;Can't load '$file' for module $module: &quot; . dl_error());
    };
    push(@DynaLoader::dl_librefs,$libref);  # record loaded object

    $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
        require Carp;
        Carp::croak(&quot;Can't find '$bootname' symbol in $file\n&quot;);
    };

    push(@DynaLoader::dl_modules, $module); # record loaded module

  boot:
    my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file);

    # See comment block above
    push(@DynaLoader::dl_shared_objects, $file); # record files loaded
    return &amp;$xs(@_);
}

sub bootstrap_inherit {
    require DynaLoader;
    goto \&amp;DynaLoader::bootstrap_inherit;
}

1;


__END__

=head1 NAME

XSLoader - Dynamically load C libraries into Perl code

=head1 VERSION

Version 0.24

=head1 SYNOPSIS

    package YourPackage;
    require XSLoader;

    XSLoader::load();

=head1 DESCRIPTION

This module defines a standard I&lt;simplified&gt; interface to the dynamic
linking mechanisms available on many platforms.  Its primary purpose is
to implement cheap automatic dynamic loading of Perl modules.

For a more complicated interface, see L&lt;DynaLoader&gt;.  Many (most)
features of C&lt;DynaLoader&gt; are not implemented in C&lt;XSLoader&gt;, like for
example the C&lt;dl_load_flags&gt;, not honored by C&lt;XSLoader&gt;.

=head2 Migration from C&lt;DynaLoader&gt;

A typical module using L&lt;DynaLoader|DynaLoader&gt; starts like this:

    package YourPackage;
    require DynaLoader;

    our @ISA = qw( OnePackage OtherPackage DynaLoader );
    our $VERSION = '0.01';
    bootstrap YourPackage $VERSION;

Change this to

    package YourPackage;
    use XSLoader;

    our @ISA = qw( OnePackage OtherPackage );
    our $VERSION = '0.01';
    XSLoader::load 'YourPackage', $VERSION;

In other words: replace C&lt;require DynaLoader&gt; by C&lt;use XSLoader&gt;, remove
C&lt;DynaLoader&gt; from C&lt;@ISA&gt;, change C&lt;bootstrap&gt; by C&lt;XSLoader::load&gt;.  Do not
forget to quote the name of your package on the C&lt;XSLoader::load&gt; line,
and add comma (C&lt;,&gt;) before the arguments (C&lt;$VERSION&gt; above).

Of course, if C&lt;@ISA&gt; contained only C&lt;DynaLoader&gt;, there is no need to have
the C&lt;@ISA&gt; assignment at all; moreover, if instead of C&lt;our&gt; one uses the
more backward-compatible

    use vars qw($VERSION @ISA);

one can remove this reference to C&lt;@ISA&gt; together with the C&lt;@ISA&gt; assignment.

If no C&lt;$VERSION&gt; was specified on the C&lt;bootstrap&gt; line, the last line becomes

    XSLoader::load 'YourPackage';

If the call to C&lt;load&gt; is from C&lt;YourPackage&gt;, then that can be further
simplified to

    XSLoader::load();

as C&lt;load&gt; will use C&lt;caller&gt; to determine the package.

=head2 Backward compatible boilerplate

If you want to have your cake and eat it too, you need a more complicated
boilerplate.

    package YourPackage;
    use vars qw($VERSION @ISA);

    @ISA = qw( OnePackage OtherPackage );
    $VERSION = '0.01';
    eval {
       require XSLoader;
       XSLoader::load('YourPackage', $VERSION);
       1;
    } or do {
       require DynaLoader;
       push @ISA, 'DynaLoader';
       bootstrap YourPackage $VERSION;
    };

The parentheses about C&lt;XSLoader::load()&gt; arguments are needed since we replaced
C&lt;use XSLoader&gt; by C&lt;require&gt;, so the compiler does not know that a function
C&lt;XSLoader::load()&gt; is present.

This boilerplate uses the low-overhead C&lt;XSLoader&gt; if present; if used with
an antique Perl which has no C&lt;XSLoader&gt;, it falls back to using C&lt;DynaLoader&gt;.

=head1 Order of initialization: early load()

I&lt;Skip this section if the XSUB functions are supposed to be called from other
modules only; read it only if you call your XSUBs from the code in your module,
or have a C&lt;BOOT:&gt; section in your XS file (see L&lt;perlxs/&quot;The BOOT: Keyword&quot;&gt;).
What is described here is equally applicable to the L&lt;DynaLoader|DynaLoader&gt;
interface.&gt;

A sufficiently complicated module using XS would have both Perl code (defined
in F&lt;YourPackage.pm&gt;) and XS code (defined in F&lt;YourPackage.xs&gt;).  If this
Perl code makes calls into this XS code, and/or this XS code makes calls to
the Perl code, one should be careful with the order of initialization.

The call to C&lt;XSLoader::load()&gt; (or C&lt;bootstrap()&gt;) calls the module's
bootstrap code. For modules build by F&lt;xsubpp&gt; (nearly all modules) this
has three side effects:

=over

=item *

A sanity check is done to ensure that the versions of the F&lt;.pm&gt; and the
(compiled) F&lt;.xs&gt; parts are compatible. If C&lt;$VERSION&gt; was specified, this
is used for the check. If not specified, it defaults to
C&lt;$XS_VERSION // $VERSION&gt; (in the module's namespace)

=item *

the XSUBs are made accessible from Perl

=item *

if a C&lt;BOOT:&gt; section was present in the F&lt;.xs&gt; file, the code there is called.

=back

Consequently, if the code in the F&lt;.pm&gt; file makes calls to these XSUBs, it is
convenient to have XSUBs installed before the Perl code is defined; for
example, this makes prototypes for XSUBs visible to this Perl code.
Alternatively, if the C&lt;BOOT:&gt; section makes calls to Perl functions (or
uses Perl variables) defined in the F&lt;.pm&gt; file, they must be defined prior to
the call to C&lt;XSLoader::load()&gt; (or C&lt;bootstrap()&gt;).

The first situation being much more frequent, it makes sense to rewrite the
boilerplate as

    package YourPackage;
    use XSLoader;
    use vars qw($VERSION @ISA);

    BEGIN {
       @ISA = qw( OnePackage OtherPackage );
       $VERSION = '0.01';

       # Put Perl code used in the BOOT: section here

       XSLoader::load 'YourPackage', $VERSION;
    }

    # Put Perl code making calls into XSUBs here

=head2 The most hairy case

If the interdependence of your C&lt;BOOT:&gt; section and Perl code is
more complicated than this (e.g., the C&lt;BOOT:&gt; section makes calls to Perl
functions which make calls to XSUBs with prototypes), get rid of the C&lt;BOOT:&gt;
section altogether.  Replace it with a function C&lt;onBOOT()&gt;, and call it like
this:

    package YourPackage;
    use XSLoader;
    use vars qw($VERSION @ISA);

    BEGIN {
       @ISA = qw( OnePackage OtherPackage );
       $VERSION = '0.01';
       XSLoader::load 'YourPackage', $VERSION;
    }

    # Put Perl code used in onBOOT() function here; calls to XSUBs are
    # prototype-checked.

    onBOOT;

    # Put Perl initialization code assuming that XS is initialized here


=head1 DIAGNOSTICS

=over

=item C&lt;Can't find '%s' symbol in %s&gt;

B&lt;(F)&gt; The bootstrap symbol could not be found in the extension module.

=item C&lt;Can't load '%s' for module %s: %s&gt;

B&lt;(F)&gt; The loading or initialisation of the extension module failed.
The detailed error follows.

=item C&lt;Undefined symbols present after loading %s: %s&gt;

B&lt;(W)&gt; As the message says, some symbols stay undefined although the
extension module was correctly loaded and initialised. The list of undefined
symbols follows.

=back

=head1 LIMITATIONS

To reduce the overhead as much as possible, only one possible location
is checked to find the extension DLL (this location is where C&lt;make install&gt;
would put the DLL).  If not found, the search for the DLL is transparently
delegated to C&lt;DynaLoader&gt;, which looks for the DLL along the C&lt;@INC&gt; list.

In particular, this is applicable to the structure of C&lt;@INC&gt; used for testing
not-yet-installed extensions.  This means that running uninstalled extensions
may have much more overhead than running the same extensions after
C&lt;make install&gt;.


=head1 KNOWN BUGS

The new simpler way to call C&lt;XSLoader::load()&gt; with no arguments at all
does not work on Perl 5.8.4 and 5.8.5.


=head1 BUGS

Please report any bugs or feature requests via the perlbug(1) utility.


=head1 SEE ALSO

L&lt;DynaLoader&gt;


=head1 AUTHORS

Ilya Zakharevich originally extracted C&lt;XSLoader&gt; from C&lt;DynaLoader&gt;.

CPAN version is currently maintained by SE&lt;eacute&gt;bastien Aperghis-Tramoni
E&lt;lt&gt;sebastien@aperghis.netE&lt;gt&gt;.

Previous maintainer was Michael G Schwern &lt;schwern@pobox.com&gt;.


=head1 COPYRIGHT &amp; LICENSE

Copyright (C) 1990-2011 by Larry Wall and others.

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

=cut
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Fshare%2Fperl5'>Back to Directory</a>