rpms/perl-ExtUtils-ParseXS
7
0
Fork 0
Code Issues Pull Requests Releases Activity
0752f3325e
perl-ExtUtils-ParseXS/ExtUtils-ParseXS-3.44-Upgrade-to-3.51.patch
Jitka Plesnikova d4f18f78dd Upgrade to 3.51 as provided in perl-5.37.12
2023-06-12 14:17:33 +02:00

5872 lines
201 KiB
Diff
Raw Blame History

From fe91c19abedf97ac1f159fb3ab27cc54cc1d8e90 Mon Sep 17 00:00:00 2001
From: Jitka Plesnikova <jplesnik@redhat.com>
Date: Mon, 12 Jun 2023 13:51:25 +0200
Subject: [PATCH] Upgrade to 3.51
---
Changes | 3 +
lib/ExtUtils/ParseXS.pm | 206 +-
lib/ExtUtils/ParseXS.pod | 10 +
lib/ExtUtils/ParseXS/Constants.pm | 2 +-
lib/ExtUtils/ParseXS/CountLines.pm | 2 +-
lib/ExtUtils/ParseXS/Eval.pm | 2 +-
lib/ExtUtils/ParseXS/Utilities.pm | 81 +-
lib/ExtUtils/Typemaps.pm | 4 +-
lib/ExtUtils/Typemaps/Cmd.pm | 2 +-
lib/ExtUtils/Typemaps/InputMap.pm | 2 +-
lib/ExtUtils/Typemaps/OutputMap.pm | 2 +-
lib/ExtUtils/Typemaps/Type.pm | 2 +-
lib/perlxs.pod | 2429 +++++++++++++++++++++++
lib/perlxstut.pod | 1425 +++++++++++++
lib/perlxstypemap.pod | 711 +++++++
t/001-basic.t | 184 +-
t/002-more.t | 9 +-
t/003-usage.t | 2 +-
t/101-standard_typemap_locations.t | 0
t/102-trim_whitespace.t | 0
t/103-tidy_type.t | 0
t/104-map_type.t | 0
t/105-valid_proto_string.t | 0
t/106-process_typemaps.t | 0
t/108-map_type.t | 0
t/109-standard_XS_defs.t | 0
t/110-assign_func_args.t | 0
t/111-analyze_preprocessor_statements.t | 0
t/112-set_cond.t | 0
t/113-check_cond_preproc_statements.t | 0
t/114-blurt_death_Warn.t | 0
t/115-avoid-noise.t | 0
t/501-t-compile.t | 0
t/510-t-bare.t | 0
t/511-t-whitespace.t | 0
t/512-t-file.t | 0
t/513-t-merge.t | 0
t/514-t-embed.t | 0
t/515-t-cmd.t | 0
t/516-t-clone.t | 0
t/517-t-targetable.t | 0
t/600-t-compat.t | 0
t/XSAlias.xs | 19 +
t/XSFalsePositive.xs | 23 +
t/XSFalsePositive2.xs | 23 +
t/XSMore.xs | 18 +
t/XSNoMap.xs | 16 +
t/XSTightDirectives.xs | 21 +
48 files changed, 5147 insertions(+), 51 deletions(-)
create mode 100644 lib/perlxs.pod
create mode 100644 lib/perlxstut.pod
create mode 100644 lib/perlxstypemap.pod
mode change 100755 => 100644 t/001-basic.t
mode change 100755 => 100644 t/002-more.t
mode change 100755 => 100644 t/003-usage.t
mode change 100755 => 100644 t/101-standard_typemap_locations.t
mode change 100755 => 100644 t/102-trim_whitespace.t
mode change 100755 => 100644 t/103-tidy_type.t
mode change 100755 => 100644 t/104-map_type.t
mode change 100755 => 100644 t/105-valid_proto_string.t
mode change 100755 => 100644 t/106-process_typemaps.t
mode change 100755 => 100644 t/108-map_type.t
mode change 100755 => 100644 t/109-standard_XS_defs.t
mode change 100755 => 100644 t/110-assign_func_args.t
mode change 100755 => 100644 t/111-analyze_preprocessor_statements.t
mode change 100755 => 100644 t/112-set_cond.t
mode change 100755 => 100644 t/113-check_cond_preproc_statements.t
mode change 100755 => 100644 t/114-blurt_death_Warn.t
mode change 100755 => 100644 t/115-avoid-noise.t
mode change 100755 => 100644 t/501-t-compile.t
mode change 100755 => 100644 t/510-t-bare.t
mode change 100755 => 100644 t/511-t-whitespace.t
mode change 100755 => 100644 t/512-t-file.t
mode change 100755 => 100644 t/513-t-merge.t
mode change 100755 => 100644 t/514-t-embed.t
mode change 100755 => 100644 t/515-t-cmd.t
mode change 100755 => 100644 t/516-t-clone.t
mode change 100755 => 100644 t/517-t-targetable.t
mode change 100755 => 100644 t/600-t-compat.t
create mode 100644 t/XSAlias.xs
create mode 100644 t/XSFalsePositive.xs
create mode 100644 t/XSFalsePositive2.xs
create mode 100644 t/XSNoMap.xs
create mode 100644 t/XSTightDirectives.xs
diff --git a/Changes b/Changes
index c4da004..8a30751 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,8 @@
Revision history for Perl extension ExtUtils::ParseXS.
+3.45 - Fri Mar 4 22:42:03 2022
+ - GH #19320: Fix OVERLOAD and FALLBACK handling.
+
3.44 - Thu Jan 6 23:49:25 2022
- GH #19054: Always XSprePUSH when producing an output list.
- Use more descriptive variable names.
diff --git a/lib/ExtUtils/ParseXS.pm b/lib/ExtUtils/ParseXS.pm
index c3e8220..0721582 100644
--- a/lib/ExtUtils/ParseXS.pm
+++ b/lib/ExtUtils/ParseXS.pm
@@ -11,7 +11,7 @@ use Symbol;
our $VERSION;
BEGIN {
- $VERSION = '3.44';
+ $VERSION = '3.51';
require ExtUtils::ParseXS::Constants; ExtUtils::ParseXS::Constants->VERSION($VERSION);
require ExtUtils::ParseXS::CountLines; ExtUtils::ParseXS::CountLines->VERSION($VERSION);
require ExtUtils::ParseXS::Utilities; ExtUtils::ParseXS::Utilities->VERSION($VERSION);
@@ -31,6 +31,7 @@ use ExtUtils::ParseXS::Utilities qw(
analyze_preprocessor_statements
set_cond
Warn
+ WarnHint
current_line_number
blurt
death
@@ -47,7 +48,10 @@ our @EXPORT_OK = qw(
##############################
# A number of "constants"
-
+our $DIE_ON_ERROR;
+our $AUTHOR_WARNINGS;
+$AUTHOR_WARNINGS = ($ENV{AUTHOR_WARNINGS} || 0)
+ unless defined $AUTHOR_WARNINGS;
our ($C_group_rex, $C_arg);
# Group in C (no support for comments or literals)
$C_group_rex = qr/ [({\[]
@@ -103,6 +107,8 @@ sub process_file {
typemap => [],
versioncheck => 1,
FH => Symbol::gensym(),
+ die_on_error => $DIE_ON_ERROR, # if true we die() and not exit() after errors
+ author_warnings => $AUTHOR_WARNINGS,
%options,
);
$args{except} = $args{except} ? ' TRY' : '';
@@ -119,9 +125,9 @@ sub process_file {
}
@{ $self->{XSStack} } = ({type => 'none'});
$self->{InitFileCode} = [ @ExtUtils::ParseXS::Constants::InitFileCode ];
- $self->{Overload} = 0; # bool
+ $self->{Overloaded} = {}; # hashref of Package => Packid
+ $self->{Fallback} = {}; # hashref of Package => fallback setting
$self->{errors} = 0; # count
- $self->{Fallback} = '&PL_sv_undef';
# Most of the 1500 lines below uses these globals. We'll have to
# clean this up sometime, probably. For now, we just pull them out
@@ -133,6 +139,9 @@ sub process_file {
$self->{WantLineNumbers} = $args{linenumbers};
$self->{IncludedFiles} = {};
+ $self->{die_on_error} = $args{die_on_error};
+ $self->{author_warnings} = $args{author_warnings};
+
die "Missing required parameter 'filename'" unless $args{filename};
$self->{filepathname} = $args{filename};
($self->{dir}, $self->{filename}) =
@@ -301,6 +310,7 @@ EOM
$self->{interface_macro_set} = 'XSINTERFACE_FUNC_SET';
$self->{ProtoThisXSUB} = $self->{WantPrototypes}; # states 0 (none), 1 (yes), 2 (empty prototype)
$self->{ScopeThisXSUB} = 0; # bool
+ $self->{OverloadsThisXSUB} = {}; # overloaded operators (as hash keys, to de-dup)
my $xsreturn = 0;
@@ -626,7 +636,16 @@ EOF
$self->print_section();
$self->death("PPCODE must be last thing") if @{ $self->{line} };
print "\tLEAVE;\n" if $self->{ScopeThisXSUB};
+ print "#if defined(__HP_cc) || defined(__HP_aCC)\n",
+ "#pragma diag_suppress 2111\n",
+ "#endif\n"
+ if $^O eq "hpux";
print "\tPUTBACK;\n\treturn;\n";
+ print "#if defined(__HP_cc) || defined(__HP_aCC)\n",
+ "#pragma diag_default 2111\n",
+ "#endif\n"
+ if $^O eq "hpux";
+
}
elsif ($self->check_keyword("CODE")) {
my $consumed_code = $self->print_section();
@@ -788,6 +807,10 @@ EOF
# if (errbuf[0])
# Perl_croak(aTHX_ errbuf);
EOF
+ print "#if defined(__HP_cc) || defined(__HP_aCC)\n",
+ "#pragma diag_suppress 2128\n",
+ "#endif\n"
+ if $^O eq "hpux";
if ($xsreturn) {
print Q(<<"EOF") unless $PPCODE;
@@ -799,6 +822,10 @@ EOF
# XSRETURN_EMPTY;
EOF
}
+ print "#if defined(__HP_cc) || defined(__HP_aCC)\n",
+ "#pragma diag_default 2128\n",
+ "#endif\n"
+ if $^O eq "hpux";
print Q(<<"EOF");
#]]
@@ -871,12 +898,20 @@ EOF
push(@{ $self->{InitFileCode} },
" (void)$self->{newXS}(\"$self->{pname}\", XS_$self->{Full_func_name}$self->{file}$self->{proto});\n");
}
+
+ for my $operator (sort keys %{ $self->{OverloadsThisXSUB} }) {
+ $self->{Overloaded}->{$self->{Package}} = $self->{Packid};
+ my $overload = "$self->{Package}\::($operator";
+ push(@{ $self->{InitFileCode} },
+ " (void)$self->{newXS}(\"$overload\", XS_$self->{Full_func_name}$self->{file}$self->{proto});\n");
+ }
} # END 'PARAGRAPH' 'while' loop
- if ($self->{Overload}) { # make it findable with fetchmethod
+ for my $package (sort keys %{ $self->{Overloaded} }) { # make them findable with fetchmethod
+ my $packid = $self->{Overloaded}->{$package};
print Q(<<"EOF");
-#XS_EUPXS(XS_$self->{Packid}_nil); /* prototype to pass -Wmissing-prototypes */
-#XS_EUPXS(XS_$self->{Packid}_nil)
+#XS_EUPXS(XS_${packid}_nil); /* prototype to pass -Wmissing-prototypes */
+#XS_EUPXS(XS_${packid}_nil)
#{
# dXSARGS;
# PERL_UNUSED_VAR(items);
@@ -884,11 +919,11 @@ EOF
#}
#
EOF
- unshift(@{ $self->{InitFileCode} }, <<"MAKE_FETCHMETHOD_WORK");
- /* Making a sub named "$self->{Package}::()" allows the package */
- /* to be findable via fetchmethod(), and causes */
- /* overload::Overloaded("$self->{Package}") to return true. */
- (void)$self->{newXS}("$self->{Package}::()", XS_$self->{Packid}_nil$self->{file}$self->{proto});
+ unshift(@{ $self->{InitFileCode} }, Q(<<"MAKE_FETCHMETHOD_WORK"));
+# /* Making a sub named "${package}::()" allows the package */
+# /* to be findable via fetchmethod(), and causes */
+# /* overload::Overloaded("$package") to return true. */
+# (void)newXS_deffile("${package}::()", XS_${packid}_nil);
MAKE_FETCHMETHOD_WORK
}
@@ -896,7 +931,7 @@ MAKE_FETCHMETHOD_WORK
print Q(<<"EOF");
##ifdef __cplusplus
-#extern "C"
+#extern "C" {
##endif
EOF
@@ -959,19 +994,28 @@ EOF
#
EOF
- print Q(<<"EOF") if ($self->{Overload});
+ if (keys %{ $self->{Overloaded} }) {
+ # once if any overloads
+ print Q(<<"EOF");
# /* register the overloading (type 'A') magic */
##if PERL_VERSION_LE(5, 8, 999) /* PERL_VERSION_LT is 5.33+ */
# PL_amagic_generation++;
##endif
+EOF
+ for my $package (sort keys %{ $self->{Overloaded} }) {
+ # once for each package with overloads
+ my $fallback = $self->{Fallback}->{$package} || "&PL_sv_undef";
+ print Q(<<"EOF");
# /* The magic for overload gets a GV* via gv_fetchmeth as */
# /* mentioned above, and looks in the SV* slot of it for */
# /* the "fallback" status. */
# sv_setsv(
-# get_sv( "$self->{Package}::()", TRUE ),
-# $self->{Fallback}
+# get_sv( "${package}::()", TRUE ),
+# $fallback
# );
EOF
+ }
+ }
print @{ $self->{InitFileCode} };
@@ -998,6 +1042,9 @@ EOF
##endif
#]]
#
+##ifdef __cplusplus
+#}
+##endif
EOF
warn("Please specify prototyping behavior for $self->{filename} (see perlxs manual)\n")
@@ -1292,26 +1339,89 @@ sub get_aliases {
my ($line) = @_;
my ($orig) = $line;
+ # we use this later for symbolic aliases
+ my $fname = $self->{Packprefix} . $self->{func_name};
+
# Parse alias definitions
# format is
- # alias = value alias = value ...
-
- while ($line =~ s/^\s*([\w:]+)\s*=\s*(\w+)\s*//) {
- my ($alias, $value) = ($1, $2);
+ # alias = value Pack::alias = value ...
+ # or
+ # alias => other
+ # or
+ # alias => Pack::other
+ # or
+ # Pack::alias => Other::alias
+
+ while ($line =~ s/^\s*([\w:]+)\s*=(>?)\s*([\w:]+)\s*//) {
+ my ($alias, $is_symbolic, $value) = ($1, $2, $3);
my $orig_alias = $alias;
+ blurt( $self, "Error: In alias definition for '$alias' the value may not"
+ . " contain ':' unless it is symbolic.")
+ if !$is_symbolic and $value=~/:/;
+
# check for optional package definition in the alias
$alias = $self->{Packprefix} . $alias if $alias !~ /::/;
+ if ($is_symbolic) {
+ my $orig_value = $value;
+ $value = $self->{Packprefix} . $value if $value !~ /::/;
+ if (defined $self->{XsubAliases}->{$value}) {
+ $value = $self->{XsubAliases}->{$value};
+ } elsif ($value eq $fname) {
+ $value = 0;
+ } else {
+ blurt( $self, "Error: Unknown alias '$value' in symbolic definition for '$orig_alias'");
+ }
+ }
+
# check for duplicate alias name & duplicate value
- Warn( $self, "Warning: Ignoring duplicate alias '$orig_alias'")
- if defined $self->{XsubAliases}->{$alias};
+ my $prev_value = $self->{XsubAliases}->{$alias};
+ if (defined $prev_value) {
+ if ($prev_value eq $value) {
+ Warn( $self, "Warning: Ignoring duplicate alias '$orig_alias'")
+ } else {
+ Warn( $self, "Warning: Conflicting duplicate alias '$orig_alias'"
+ . " changes definition from '$prev_value' to '$value'");
+ delete $self->{XsubAliasValues}->{$prev_value}{$alias};
+ }
+ }
- Warn( $self, "Warning: Aliases '$orig_alias' and '$self->{XsubAliasValues}->{$value}' have identical values")
- if $self->{XsubAliasValues}->{$value};
+ # Check and see if this alias results in two aliases having the same
+ # value, we only check non-symbolic definitions as the whole point of
+ # symbolic definitions is to say we want to duplicate the value and
+ # it is NOT a mistake.
+ unless ($is_symbolic) {
+ my @keys= sort keys %{$self->{XsubAliasValues}->{$value}||{}};
+ # deal with an alias of 0, which might not be in the XsubAlias dataset
+ # yet as 0 is the default for the base function ($fname)
+ push @keys, $fname
+ if $value eq "0" and !defined $self->{XsubAlias}{$fname};
+ if (@keys and $self->{author_warnings}) {
+ # We do not warn about value collisions unless author_warnings
+ # are enabled. They aren't helpful to a module consumer, only
+ # the module author.
+ @keys= map { "'$_'" }
+ map { my $copy= $_;
+ $copy=~s/^$self->{Packprefix}//;
+ $copy
+ } @keys;
+ WarnHint( $self,
+ "Warning: Aliases '$orig_alias' and "
+ . join(", ", @keys)
+ . " have identical values of $value"
+ . ( $value eq "0"
+ ? " - the base function"
+ : "" ),
+ !$self->{XsubAliasValueClashHinted}++
+ ? "If this is deliberate use a symbolic alias instead."
+ : undef
+ );
+ }
+ }
$self->{XsubAliases}->{$alias} = $value;
- $self->{XsubAliasValues}->{$value} = $orig_alias;
+ $self->{XsubAliasValues}->{$value}{$alias}++;
}
blurt( $self, "Error: Cannot parse ALIAS definitions from '$orig'")
@@ -1348,10 +1458,7 @@ sub OVERLOAD_handler {
next unless /\S/;
trim_whitespace($_);
while ( s/^\s*([\w:"\\)\+\-\*\/\%\<\>\.\&\|\^\!\~\{\}\=]+)\s*//) {
- $self->{Overload} = 1 unless $self->{Overload};
- my $overload = "$self->{Package}\::(".$1;
- push(@{ $self->{InitFileCode} },
- " (void)$self->{newXS}(\"$overload\", XS_$self->{Full_func_name}$self->{file}$self->{proto});\n");
+ $self->{OverloadsThisXSUB}->{$1} = 1;
}
}
}
@@ -1374,7 +1481,7 @@ sub FALLBACK_handler {
# check for valid FALLBACK value
$self->death("Error: FALLBACK: TRUE/FALSE/UNDEF") unless exists $map{$setting};
- $self->{Fallback} = $map{$setting};
+ $self->{Fallback}->{$self->{Package}} = $map{$setting};
}
@@ -1785,11 +1892,17 @@ sub fetch_para {
$self->_process_module_xs_line($1, $2, $3);
}
+ # count how many #ifdef levels we see in this paragraph
+ # decrementing when we see an endif. if we see an elsif
+ # or endif without a corresponding #ifdef then we dont
+ # consider it part of this paragraph.
+ my $if_level = 0;
for (;;) {
$self->_maybe_skip_pod;
$self->_maybe_parse_typemap_block;
+ my $final;
if ($self->{lastline} !~ /^\s*#/ # not a CPP directive
# CPP directives:
# ANSI: if ifdef ifndef elif else endif define undef
@@ -1799,7 +1912,7 @@ sub fetch_para {
# others: ident (gcc notes that some cpps have this one)
|| $self->{lastline} =~ /^\#[ \t]*
(?:
- (?:if|ifn?def|elif|else|endif|
+ (?:if|ifn?def|elif|else|endif|elifn?def|
define|undef|pragma|error|
warning|line\s+\d+|ident)
\b
@@ -1810,6 +1923,31 @@ sub fetch_para {
)
{
last if $self->{lastline} =~ /^\S/ && @{ $self->{line} } && $self->{line}->[-1] eq "";
+ if ($self->{lastline}=~/^#[ \t]*(if|ifn?def|elif|else|endif|elifn?def)\b/) {
+ my $type = $1; # highest defined capture buffer, "if" for any if like condition
+ if ($type =~ /^if/) {
+ if (@{$self->{line}}) {
+ # increment level
+ $if_level++;
+ } else {
+ $final = 1;
+ }
+ } elsif ($type eq "endif") {
+ if ($if_level) { # are we in an if that was started in this paragraph?
+ $if_level--; # yep- so decrement to end this if block
+ } else {
+ $final = 1;
+ }
+ } elsif (!$if_level) {
+ # not in an #ifdef from this paragraph, thus
+ # this directive should not be part of this paragraph.
+ $final = 1;
+ }
+ }
+ if ($final and @{$self->{line}}) {
+ return 1;
+ }
+
push(@{ $self->{line} }, $self->{lastline});
push(@{ $self->{line_no} }, $self->{lastline_no});
}
@@ -1823,6 +1961,9 @@ sub fetch_para {
chomp $self->{lastline};
$self->{lastline} =~ s/^\s+$//;
+ if ($final) {
+ last;
+ }
}
# Nuke trailing "line" entries until there's one that's not empty
@@ -2028,8 +2169,9 @@ sub generate_output {
(my $ntype = $type) =~ s/\s*\*/Ptr/g;
$ntype =~ s/\(\)//g;
(my $subtype = $ntype) =~ s/(?:Array)?(?:Ptr)?$//;
+ $type =~ tr/:/_/ unless $self->{RetainCplusplusHierarchicalTypes};
- my $eval_vars = {%$argsref, subtype => $subtype, ntype => $ntype, arg => $arg};
+ my $eval_vars = {%$argsref, subtype => $subtype, ntype => $ntype, arg => $arg, type => $type };
my $expr = $outputmap->cleaned_code;
if ($expr =~ /DO_ARRAY_ELEM/) {
my $subtypemap = $typemaps->get_typemap(ctype => $subtype);
diff --git a/lib/ExtUtils/ParseXS.pod b/lib/ExtUtils/ParseXS.pod
index 80bf13f..093a317 100644
--- a/lib/ExtUtils/ParseXS.pod
+++ b/lib/ExtUtils/ParseXS.pod
@@ -19,6 +19,7 @@ ExtUtils::ParseXS - converts Perl XS code into C code
linenumbers => 1,
optimize => 1,
prototypes => 1,
+ die_on_error => 0,
);
# Legacy non-OO interface using a singleton:
@@ -119,6 +120,15 @@ Default is true.
I<Maintainer note:> I have no clue what this does. Strips function prefixes?
+=item B<die_on_error>
+
+Normally ExtUtils::ParseXS will terminate the program with an C<exit(1)> after
+printing the details of the exception to STDERR via (warn). This can be awkward
+when it is used programmatically and not via xsubpp, so this option can be used
+to cause it to die instead by providing a true value. When not provided this
+defaults to the value of C<$ExtUtils::ParseXS::DIE_ON_ERROR> which in turn
+defaults to false.
+
=back
=item $pxs->report_error_count()
diff --git a/lib/ExtUtils/ParseXS/Constants.pm b/lib/ExtUtils/ParseXS/Constants.pm
index 5b73795..012ba55 100644
--- a/lib/ExtUtils/ParseXS/Constants.pm
+++ b/lib/ExtUtils/ParseXS/Constants.pm
@@ -3,7 +3,7 @@ use strict;
use warnings;
use Symbol;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
=head1 NAME
diff --git a/lib/ExtUtils/ParseXS/CountLines.pm b/lib/ExtUtils/ParseXS/CountLines.pm
index a5b71f6..cca6e74 100644
--- a/lib/ExtUtils/ParseXS/CountLines.pm
+++ b/lib/ExtUtils/ParseXS/CountLines.pm
@@ -1,7 +1,7 @@
package ExtUtils::ParseXS::CountLines;
use strict;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
our $SECTION_END_MARKER;
diff --git a/lib/ExtUtils/ParseXS/Eval.pm b/lib/ExtUtils/ParseXS/Eval.pm
index 8a3bd00..a7c3920 100644
--- a/lib/ExtUtils/ParseXS/Eval.pm
+++ b/lib/ExtUtils/ParseXS/Eval.pm
@@ -2,7 +2,7 @@ package ExtUtils::ParseXS::Eval;
use strict;
use warnings;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
=head1 NAME
diff --git a/lib/ExtUtils/ParseXS/Utilities.pm b/lib/ExtUtils/ParseXS/Utilities.pm
index 574031d..b2674b3 100644
--- a/lib/ExtUtils/ParseXS/Utilities.pm
+++ b/lib/ExtUtils/ParseXS/Utilities.pm
@@ -5,7 +5,7 @@ use Exporter;
use File::Spec;
use ExtUtils::ParseXS::Constants ();
-our $VERSION = '3.44';
+our $VERSION = '3.51';
our (@ISA, @EXPORT_OK);
@ISA = qw(Exporter);
@@ -21,6 +21,7 @@ our (@ISA, @EXPORT_OK);
analyze_preprocessor_statements
set_cond
Warn
+ WarnHint
current_line_number
blurt
death
@@ -654,18 +655,85 @@ sub current_line_number {
=item * Purpose
+Print warnings with line number details at the end.
+
=item * Arguments
+List of text to output.
+
=item * Return Value
+None.
+
=back
=cut
sub Warn {
+ my ($self)=shift;
+ $self->WarnHint(@_,undef);
+}
+
+=head2 C<WarnHint()>
+
+=over 4
+
+=item * Purpose
+
+Prints warning with line number details. The last argument is assumed
+to be a hint string.
+
+=item * Arguments
+
+List of strings to warn, followed by one argument representing a hint.
+If that argument is defined then it will be split on newlines and output
+line by line after the main warning.
+
+=item * Return Value
+
+None.
+
+=back
+
+=cut
+
+sub WarnHint {
+ warn _MsgHint(@_);
+}
+
+=head2 C<_MsgHint()>
+
+=over 4
+
+=item * Purpose
+
+Constructs an exception message with line number details. The last argument is
+assumed to be a hint string.
+
+=item * Arguments
+
+List of strings to warn, followed by one argument representing a hint.
+If that argument is defined then it will be split on newlines and concatenated
+line by line (parenthesized) after the main message.
+
+=item * Return Value
+
+The constructed string.
+
+=back
+
+=cut
+
+
+sub _MsgHint {
my $self = shift;
+ my $hint = pop;
my $warn_line_number = $self->current_line_number();
- print STDERR "@_ in $self->{filename}, line $warn_line_number\n";
+ my $ret = join("",@_) . " in $self->{filename}, line $warn_line_number\n";
+ if ($hint) {
+ $ret .= " ($_)\n" for split /\n/, $hint;
+ }
+ return $ret;
}
=head2 C<blurt()>
@@ -703,8 +771,13 @@ sub blurt {
=cut
sub death {
- my $self = shift;
- $self->Warn(@_);
+ my ($self) = (@_);
+ my $message = _MsgHint(@_,"");
+ if ($self->{die_on_error}) {
+ die $message;
+ } else {
+ warn $message;
+ }
exit 1;
}
diff --git a/lib/ExtUtils/Typemaps.pm b/lib/ExtUtils/Typemaps.pm
index c6d5430..2a324a6 100644
--- a/lib/ExtUtils/Typemaps.pm
+++ b/lib/ExtUtils/Typemaps.pm
@@ -2,7 +2,7 @@ package ExtUtils::Typemaps;
use 5.006001;
use strict;
use warnings;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
require ExtUtils::ParseXS;
require ExtUtils::ParseXS::Constants;
@@ -378,7 +378,7 @@ sub remove_inputmap {
return $self->_remove($xstype, $self->{input_section}, $self->{input_lookup});
}
-=head2 remove_inputmap
+=head2 remove_outputmap
Removes an C<OUTPUT> entry from the typemap.
diff --git a/lib/ExtUtils/Typemaps/Cmd.pm b/lib/ExtUtils/Typemaps/Cmd.pm
index 3c4b4e5..73f8b71 100644
--- a/lib/ExtUtils/Typemaps/Cmd.pm
+++ b/lib/ExtUtils/Typemaps/Cmd.pm
@@ -2,7 +2,7 @@ package ExtUtils::Typemaps::Cmd;
use 5.006001;
use strict;
use warnings;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
use ExtUtils::Typemaps;
diff --git a/lib/ExtUtils/Typemaps/InputMap.pm b/lib/ExtUtils/Typemaps/InputMap.pm
index 102fc9e..5b18021 100644
--- a/lib/ExtUtils/Typemaps/InputMap.pm
+++ b/lib/ExtUtils/Typemaps/InputMap.pm
@@ -2,7 +2,7 @@ package ExtUtils::Typemaps::InputMap;
use 5.006001;
use strict;
use warnings;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
=head1 NAME
diff --git a/lib/ExtUtils/Typemaps/OutputMap.pm b/lib/ExtUtils/Typemaps/OutputMap.pm
index f9b5a86..d5aacdb 100644
--- a/lib/ExtUtils/Typemaps/OutputMap.pm
+++ b/lib/ExtUtils/Typemaps/OutputMap.pm
@@ -2,7 +2,7 @@ package ExtUtils::Typemaps::OutputMap;
use 5.006001;
use strict;
use warnings;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
=head1 NAME
diff --git a/lib/ExtUtils/Typemaps/Type.pm b/lib/ExtUtils/Typemaps/Type.pm
index 1a78c17..9970281 100644
--- a/lib/ExtUtils/Typemaps/Type.pm
+++ b/lib/ExtUtils/Typemaps/Type.pm
@@ -4,7 +4,7 @@ use strict;
use warnings;
require ExtUtils::Typemaps;
-our $VERSION = '3.44';
+our $VERSION = '3.51';
=head1 NAME
diff --git a/lib/perlxs.pod b/lib/perlxs.pod
new file mode 100644
index 0000000..aa7ccad
--- /dev/null
+++ b/lib/perlxs.pod
@@ -0,0 +1,2429 @@
+=head1 NAME
+
+perlxs - XS language reference manual
+
+=head1 DESCRIPTION
+
+=head2 Introduction
+
+XS is an interface description file format used to create an extension
+interface between Perl and C code (or a C library) which one wishes
+to use with Perl. The XS interface is combined with the library to
+create a new library which can then be either dynamically loaded
+or statically linked into perl. The XS interface description is
+written in the XS language and is the core component of the Perl
+extension interface.
+
+Before writing XS, read the L</CAVEATS> section below.
+
+An B<XSUB> forms the basic unit of the XS interface. After compilation
+by the B<xsubpp> compiler, each XSUB amounts to a C function definition
+which will provide the glue between Perl calling conventions and C
+calling conventions.
+
+The glue code pulls the arguments from the Perl stack, converts these
+Perl values to the formats expected by a C function, calls this C function,
+and then transfers the return values of the C function back to Perl.
+Return values here may be a conventional C return value or any C
+function arguments that may serve as output parameters. These return
+values may be passed back to Perl either by putting them on the
+Perl stack, or by modifying the arguments supplied from the Perl side.
+
+The above is a somewhat simplified view of what really happens. Since
+Perl allows more flexible calling conventions than C, XSUBs may do much
+more in practice, such as checking input parameters for validity,
+throwing exceptions (or returning undef/empty list) if the return value
+from the C function indicates failure, calling different C functions
+based on numbers and types of the arguments, providing an object-oriented
+interface, etc.
+
+Of course, one could write such glue code directly in C. However, this
+would be a tedious task, especially if one needs to write glue for
+multiple C functions, and/or one is not familiar enough with the Perl
+stack discipline and other such arcana. XS comes to the rescue here:
+instead of writing this glue C code in long-hand, one can write
+a more concise short-hand I<description> of what should be done by
+the glue, and let the XS compiler B<xsubpp> handle the rest.
+
+The XS language allows one to describe the mapping between how the C
+routine is used, and how the corresponding Perl routine is used. It
+also allows creation of Perl routines which are directly translated to
+C code and which are not related to a pre-existing C function. In cases
+when the C interface coincides with the Perl interface, the XSUB
+declaration is almost identical to a declaration of a C function (in K&R
+style). In such circumstances, there is another tool called C<h2xs>
+that is able to translate an entire C header file into a corresponding
+XS file that will provide glue to the functions/macros described in
+the header file.
+
+The XS compiler is called B<xsubpp>. This compiler creates
+the constructs necessary to let an XSUB manipulate Perl values, and
+creates the glue necessary to let Perl call the XSUB. The compiler
+uses B<typemaps> to determine how to map C function parameters
+and output values to Perl values and back. The default typemap
+(which comes with Perl) handles many common C types. A supplementary
+typemap may also be needed to handle any special structures and types
+for the library being linked. For more information on typemaps,
+see L<perlxstypemap>.
+
+A file in XS format starts with a C language section which goes until the
+first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions
+may follow this line. The "language" used in this part of the file
+is usually referred to as the XS language. B<xsubpp> recognizes and
+skips POD (see L<perlpod>) in both the C and XS language sections, which
+allows the XS file to contain embedded documentation.
+
+See L<perlxstut> for a tutorial on the whole extension creation process.
+
+Note: For some extensions, Dave Beazley's SWIG system may provide a
+significantly more convenient mechanism for creating the extension
+glue code. See L<http://www.swig.org/> for more information.
+
+For simple bindings to C libraries as well as other machine code libraries,
+consider instead using the much simpler
+L<libffi|http://sourceware.org/libffi/> interface via CPAN modules like
+L<FFI::Platypus> or L<FFI::Raw>.
+
+=head2 On The Road
+
+Many of the examples which follow will concentrate on creating an interface
+between Perl and the ONC+ RPC bind library functions. The rpcb_gettime()
+function is used to demonstrate many features of the XS language. This
+function has two parameters; the first is an input parameter and the second
+is an output parameter. The function also returns a status value.
+
+ bool_t rpcb_gettime(const char *host, time_t *timep);
+
+From C this function will be called with the following
+statements.
+
+ #include <rpc/rpc.h>
+ bool_t status;
+ time_t timep;
+ status = rpcb_gettime( "localhost", &timep );
+
+If an XSUB is created to offer a direct translation between this function
+and Perl, then this XSUB will be used from Perl with the following code.
+The $status and $timep variables will contain the output of the function.
+
+ use RPC;
+ $status = rpcb_gettime( "localhost", $timep );
+
+The following XS file shows an XS subroutine, or XSUB, which
+demonstrates one possible interface to the rpcb_gettime()
+function. This XSUB represents a direct translation between
+C and Perl and so preserves the interface even from Perl.
+This XSUB will be invoked from Perl with the usage shown
+above. Note that the first three #include statements, for
+C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
+beginning of an XS file. This approach and others will be
+expanded later in this document. A #define for C<PERL_NO_GET_CONTEXT>
+should be present to fetch the interpreter context more efficiently,
+see L<perlguts|perlguts/How multiple interpreters and concurrency are
+supported> for details.
+
+ #define PERL_NO_GET_CONTEXT
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+ #include <rpc/rpc.h>
+
+ MODULE = RPC PACKAGE = RPC
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ OUTPUT:
+ timep
+
+Any extension to Perl, including those containing XSUBs,
+should have a Perl module to serve as the bootstrap which
+pulls the extension into Perl. This module will export the
+extension's functions and variables to the Perl program and
+will cause the extension's XSUBs to be linked into Perl.
+The following module will be used for most of the examples
+in this document and should be used from Perl with the C<use>
+command as shown earlier. Perl modules are explained in
+more detail later in this document.
+
+ package RPC;
+
+ require Exporter;
+ require DynaLoader;
+ @ISA = qw(Exporter DynaLoader);
+ @EXPORT = qw( rpcb_gettime );
+
+ bootstrap RPC;
+ 1;
+
+Throughout this document a variety of interfaces to the rpcb_gettime()
+XSUB will be explored. The XSUBs will take their parameters in different
+orders or will take different numbers of parameters. In each case the
+XSUB is an abstraction between Perl and the real C rpcb_gettime()
+function, and the XSUB must always ensure that the real rpcb_gettime()
+function is called with the correct parameters. This abstraction will
+allow the programmer to create a more Perl-like interface to the C
+function.
+
+=head2 The Anatomy of an XSUB
+
+The simplest XSUBs consist of 3 parts: a description of the return
+value, the name of the XSUB routine and the names of its arguments,
+and a description of types or formats of the arguments.
+
+The following XSUB allows a Perl program to access a C library function
+called sin(). The XSUB will imitate the C function which takes a single
+argument and returns a single value.
+
+ double
+ sin(x)
+ double x
+
+Optionally, one can merge the description of types and the list of
+argument names, rewriting this as
+
+ double
+ sin(double x)
+
+This makes this XSUB look similar to an ANSI C declaration. An optional
+semicolon is allowed after the argument list, as in
+
+ double
+ sin(double x);
+
+Parameters with C pointer types can have different semantic: C functions
+with similar declarations
+
+ bool string_looks_as_a_number(char *s);
+ bool make_char_uppercase(char *c);
+
+are used in absolutely incompatible manner. Parameters to these functions
+could be described to B<xsubpp> like this:
+
+ char * s
+ char &c
+
+Both these XS declarations correspond to the C<char*> C type, but they have
+different semantics, see L<"The & Unary Operator">.
+
+It is convenient to think that the indirection operator
+C<*> should be considered as a part of the type and the address operator C<&>
+should be considered part of the variable. See L<perlxstypemap>
+for more info about handling qualifiers and unary operators in C types.
+
+The function name and the return type must be placed on
+separate lines and should be flush left-adjusted.
+
+ INCORRECT CORRECT
+
+ double sin(x) double
+ double x sin(x)
+ double x
+
+The rest of the function description may be indented or left-adjusted. The
+following example shows a function with its body left-adjusted. Most
+examples in this document will indent the body for better readability.
+
+ CORRECT
+
+ double
+ sin(x)
+ double x
+
+More complicated XSUBs may contain many other sections. Each section of
+an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
+However, the first two lines of an XSUB always contain the same data:
+descriptions of the return type and the names of the function and its
+parameters. Whatever immediately follows these is considered to be
+an INPUT: section unless explicitly marked with another keyword.
+(See L<The INPUT: Keyword>.)
+
+An XSUB section continues until another section-start keyword is found.
+
+=head2 The Argument Stack
+
+The Perl argument stack is used to store the values which are
+sent as parameters to the XSUB and to store the XSUB's
+return value(s). In reality all Perl functions (including non-XSUB
+ones) keep their values on this stack all the same time, each limited
+to its own range of positions on the stack. In this document the
+first position on that stack which belongs to the active
+function will be referred to as position 0 for that function.
+
+XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
+refers to a position in this XSUB's part of the stack. Position 0 for that
+function would be known to the XSUB as ST(0). The XSUB's incoming
+parameters and outgoing return values always begin at ST(0). For many
+simple cases the B<xsubpp> compiler will generate the code necessary to
+handle the argument stack by embedding code fragments found in the
+typemaps. In more complex cases the programmer must supply the code.
+
+=head2 The RETVAL Variable
+
+The RETVAL variable is a special C variable that is declared automatically
+for you. The C type of RETVAL matches the return type of the C library
+function. The B<xsubpp> compiler will declare this variable in each XSUB
+with non-C<void> return type. By default the generated C function
+will use RETVAL to hold the return value of the C library function being
+called. In simple cases the value of RETVAL will be placed in ST(0) of
+the argument stack where it can be received by Perl as the return value
+of the XSUB.
+
+If the XSUB has a return type of C<void> then the compiler will
+not declare a RETVAL variable for that function. When using
+a PPCODE: section no manipulation of the RETVAL variable is required, the
+section may use direct stack manipulation to place output values on the stack.
+
+If PPCODE: directive is not used, C<void> return value should be used
+only for subroutines which do not return a value, I<even if> CODE:
+directive is used which sets ST(0) explicitly.
+
+Older versions of this document recommended to use C<void> return
+value in such cases. It was discovered that this could lead to
+segfaults in cases when XSUB was I<truly> C<void>. This practice is
+now deprecated, and may be not supported at some future version. Use
+the return value C<SV *> in such cases. (Currently C<xsubpp> contains
+some heuristic code which tries to disambiguate between "truly-void"
+and "old-practice-declared-as-void" functions. Hence your code is at
+mercy of this heuristics unless you use C<SV *> as return value.)
+
+=head2 Returning SVs, AVs and HVs through RETVAL
+
+When you're using RETVAL to return an C<SV *>, there's some magic
+going on behind the scenes that should be mentioned. When you're
+manipulating the argument stack using the ST(x) macro, for example,
+you usually have to pay special attention to reference counts. (For
+more about reference counts, see L<perlguts>.) To make your life
+easier, the typemap file automatically makes C<RETVAL> mortal when
+you're returning an C<SV *>. Thus, the following two XSUBs are more
+or less equivalent:
+
+ void
+ alpha()
+ PPCODE:
+ ST(0) = newSVpv("Hello World",0);
+ sv_2mortal(ST(0));
+ XSRETURN(1);
+
+ SV *
+ beta()
+ CODE:
+ RETVAL = newSVpv("Hello World",0);
+ OUTPUT:
+ RETVAL
+
+This is quite useful as it usually improves readability. While
+this works fine for an C<SV *>, it's unfortunately not as easy
+to have C<AV *> or C<HV *> as a return value. You I<should> be
+able to write:
+
+ AV *
+ array()
+ CODE:
+ RETVAL = newAV();
+ /* do something with RETVAL */
+ OUTPUT:
+ RETVAL
+
+But due to an unfixable bug (fixing it would break lots of existing
+CPAN modules) in the typemap file, the reference count of the C<AV *>
+is not properly decremented. Thus, the above XSUB would leak memory
+whenever it is being called. The same problem exists for C<HV *>,
+C<CV *>, and C<SVREF> (which indicates a scalar reference, not
+a general C<SV *>).
+In XS code on perls starting with perl 5.16, you can override the
+typemaps for any of these types with a version that has proper
+handling of refcounts. In your C<TYPEMAP> section, do
+
+ AV* T_AVREF_REFCOUNT_FIXED
+
+to get the repaired variant. For backward compatibility with older
+versions of perl, you can instead decrement the reference count
+manually when you're returning one of the aforementioned
+types using C<sv_2mortal>:
+
+ AV *
+ array()
+ CODE:
+ RETVAL = newAV();
+ sv_2mortal((SV*)RETVAL);
+ /* do something with RETVAL */
+ OUTPUT:
+ RETVAL
+
+Remember that you don't have to do this for an C<SV *>. The reference
+documentation for all core typemaps can be found in L<perlxstypemap>.
+
+=head2 The MODULE Keyword
+
+The MODULE keyword is used to start the XS code and to specify the package
+of the functions which are being defined. All text preceding the first
+MODULE keyword is considered C code and is passed through to the output with
+POD stripped, but otherwise untouched. Every XS module will have a
+bootstrap function which is used to hook the XSUBs into Perl. The package
+name of this bootstrap function will match the value of the last MODULE
+statement in the XS source files. The value of MODULE should always remain
+constant within the same XS file, though this is not required.
+
+The following example will start the XS code and will place
+all functions in a package named RPC.
+
+ MODULE = RPC
+
+=head2 The PACKAGE Keyword
+
+When functions within an XS source file must be separated into packages
+the PACKAGE keyword should be used. This keyword is used with the MODULE
+keyword and must follow immediately after it when used.
+
+ MODULE = RPC PACKAGE = RPC
+
+ [ XS code in package RPC ]
+
+ MODULE = RPC PACKAGE = RPCB
+
+ [ XS code in package RPCB ]
+
+ MODULE = RPC PACKAGE = RPC
+
+ [ XS code in package RPC ]
+
+The same package name can be used more than once, allowing for
+non-contiguous code. This is useful if you have a stronger ordering
+principle than package names.
+
+Although this keyword is optional and in some cases provides redundant
+information it should always be used. This keyword will ensure that the
+XSUBs appear in the desired package.
+
+=head2 The PREFIX Keyword
+
+The PREFIX keyword designates prefixes which should be
+removed from the Perl function names. If the C function is
+C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
+see this function as C<gettime()>.
+
+This keyword should follow the PACKAGE keyword when used.
+If PACKAGE is not used then PREFIX should follow the MODULE
+keyword.
+
+ MODULE = RPC PREFIX = rpc_
+
+ MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
+
+=head2 The OUTPUT: Keyword
+
+The OUTPUT: keyword indicates that certain function parameters should be
+updated (new values made visible to Perl) when the XSUB terminates or that
+certain values should be returned to the calling Perl function. For
+simple functions which have no CODE: or PPCODE: section,
+such as the sin() function above, the RETVAL variable is
+automatically designated as an output value. For more complex functions
+the B<xsubpp> compiler will need help to determine which variables are output
+variables.
+
+This keyword will normally be used to complement the CODE: keyword.
+The RETVAL variable is not recognized as an output variable when the
+CODE: keyword is present. The OUTPUT: keyword is used in this
+situation to tell the compiler that RETVAL really is an output
+variable.
+
+The OUTPUT: keyword can also be used to indicate that function parameters
+are output variables. This may be necessary when a parameter has been
+modified within the function and the programmer would like the update to
+be seen by Perl.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ OUTPUT:
+ timep
+
+The OUTPUT: keyword will also allow an output parameter to
+be mapped to a matching piece of code rather than to a
+typemap.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ OUTPUT:
+ timep sv_setnv(ST(1), (double)timep);
+
+B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
+OUTPUT section of the XSUB, except RETVAL. This is the usually desired
+behavior, as it takes care of properly invoking 'set' magic on output
+parameters (needed for hash or array element parameters that must be
+created if they didn't exist). If for some reason, this behavior is
+not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
+to disable it for the remainder of the parameters in the OUTPUT section.
+Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
+remainder of the OUTPUT section. See L<perlguts> for more details
+about 'set' magic.
+
+=head2 The NO_OUTPUT Keyword
+
+The NO_OUTPUT can be placed as the first token of the XSUB. This keyword
+indicates that while the C subroutine we provide an interface to has
+a non-C<void> return type, the return value of this C subroutine should not
+be returned from the generated Perl subroutine.
+
+With this keyword present L<The RETVAL Variable> is created, and in the
+generated call to the subroutine this variable is assigned to, but the value
+of this variable is not going to be used in the auto-generated code.
+
+This keyword makes sense only if C<RETVAL> is going to be accessed by the
+user-supplied code. It is especially useful to make a function interface
+more Perl-like, especially when the C return value is just an error condition
+indicator. For example,
+
+ NO_OUTPUT int
+ delete_file(char *name)
+ POSTCALL:
+ if (RETVAL != 0)
+ croak("Error %d while deleting file '%s'", RETVAL, name);
+
+Here the generated XS function returns nothing on success, and will die()
+with a meaningful error message on error.
+
+=head2 The CODE: Keyword
+
+This keyword is used in more complicated XSUBs which require
+special handling for the C function. The RETVAL variable is
+still declared, but it will not be returned unless it is specified
+in the OUTPUT: section.
+
+The following XSUB is for a C function which requires special handling of
+its parameters. The Perl usage is given first.
+
+ $status = rpcb_gettime( "localhost", $timep );
+
+The XSUB follows.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t timep
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 The INIT: Keyword
+
+The INIT: keyword allows initialization to be inserted into the XSUB before
+the compiler generates the call to the C function. Unlike the CODE: keyword
+above, this keyword does not affect the way the compiler handles RETVAL.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ INIT:
+ printf("# Host is %s\n", host );
+ OUTPUT:
+ timep
+
+Another use for the INIT: section is to check for preconditions before
+making a call to the C function:
+
+ long long
+ lldiv(a,b)
+ long long a
+ long long b
+ INIT:
+ if (a == 0 && b == 0)
+ XSRETURN_UNDEF;
+ if (b == 0)
+ croak("lldiv: cannot divide by 0");
+
+=head2 The NO_INIT Keyword
+
+The NO_INIT keyword is used to indicate that a function
+parameter is being used only as an output value. The B<xsubpp>
+compiler will normally generate code to read the values of
+all function parameters from the argument stack and assign
+them to C variables upon entry to the function. NO_INIT
+will tell the compiler that some parameters will be used for
+output rather than for input and that they will be handled
+before the function terminates.
+
+The following example shows a variation of the rpcb_gettime() function.
+This function uses the timep variable only as an output variable and does
+not care about its initial contents.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep = NO_INIT
+ OUTPUT:
+ timep
+
+=head2 The TYPEMAP: Keyword
+
+Starting with Perl 5.16, you can embed typemaps into your XS code
+instead of or in addition to typemaps in a separate file. Multiple
+such embedded typemaps will be processed in order of appearance in
+the XS code and like local typemap files take precedence over the
+default typemap, the embedded typemaps may overwrite previous
+definitions of TYPEMAP, INPUT, and OUTPUT stanzas. The syntax for
+embedded typemaps is
+
+ TYPEMAP: <<HERE
+ ... your typemap code here ...
+ HERE
+
+where the C<TYPEMAP> keyword must appear in the first column of a
+new line.
+
+Refer to L<perlxstypemap> for details on writing typemaps.
+
+=head2 Initializing Function Parameters
+
+C function parameters are normally initialized with their values from
+the argument stack (which in turn contains the parameters that were
+passed to the XSUB from Perl). The typemaps contain the
+code segments which are used to translate the Perl values to
+the C parameters. The programmer, however, is allowed to
+override the typemaps and supply alternate (or additional)
+initialization code. Initialization code starts with the first
+C<=>, C<;> or C<+> on a line in the INPUT: section. The only
+exception happens if this C<;> terminates the line, then this C<;>
+is quietly ignored.
+
+The following code demonstrates how to supply initialization code for
+function parameters. The initialization code is eval'ed within double
+quotes by the compiler before it is added to the output so anything
+which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
+must be protected with backslashes. The variables C<$var>, C<$arg>,
+and C<$type> can be used as in typemaps.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host = (char *)SvPVbyte_nolen($arg);
+ time_t &timep = 0;
+ OUTPUT:
+ timep
+
+This should not be used to supply default values for parameters. One
+would normally use this when a function parameter must be processed by
+another library function before it can be used. Default parameters are
+covered in the next section.
+
+If the initialization begins with C<=>, then it is output in
+the declaration for the input variable, replacing the initialization
+supplied by the typemap. If the initialization
+begins with C<;> or C<+>, then it is performed after
+all of the input variables have been declared. In the C<;>
+case the initialization normally supplied by the typemap is not performed.
+For the C<+> case, the declaration for the variable will include the
+initialization from the typemap. A global
+variable, C<%v>, is available for the truly rare case where
+information from one initialization is needed in another
+initialization.
+
+Here's a truly obscure example:
+
+ bool_t
+ rpcb_gettime(host,timep)
+ time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
+ char *host + SvOK($v{timep}) ? SvPVbyte_nolen($arg) : NULL;
+ OUTPUT:
+ timep
+
+The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
+example has a two-fold purpose: first, when this line is processed by
+B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
+the text of the evaluated snippet is output into the generated C file
+(inside a C comment)! During the processing of C<char *host> line,
+C<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
+C<ST(1)>.
+
+=head2 Default Parameter Values
+
+Default values for XSUB arguments can be specified by placing an
+assignment statement in the parameter list. The default value may
+be a number, a string or the special string C<NO_INIT>. Defaults should
+always be used on the right-most parameters only.
+
+To allow the XSUB for rpcb_gettime() to have a default host
+value the parameters to the XSUB could be rearranged. The
+XSUB will then call the real rpcb_gettime() function with
+the parameters in the correct order. This XSUB can be called
+from Perl with either of the following statements:
+
+ $status = rpcb_gettime( $timep, $host );
+
+ $status = rpcb_gettime( $timep );
+
+The XSUB will look like the code which follows. A CODE:
+block is used to call the real rpcb_gettime() function with
+the parameters in the correct order for that function.
+
+ bool_t
+ rpcb_gettime(timep,host="localhost")
+ char *host
+ time_t timep = NO_INIT
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 The PREINIT: Keyword
+
+The PREINIT: keyword allows extra variables to be declared immediately
+before or after the declarations of the parameters from the INPUT: section
+are emitted.
+
+If a variable is declared inside a CODE: section it will follow any typemap
+code that is emitted for the input parameters. This may result in the
+declaration ending up after C code, which is C syntax error. Similar
+errors may happen with an explicit C<;>-type or C<+>-type initialization of
+parameters is used (see L<"Initializing Function Parameters">). Declaring
+these variables in an INIT: section will not help.
+
+In such cases, to force an additional variable to be declared together
+with declarations of other variables, place the declaration into a
+PREINIT: section. The PREINIT: keyword may be used one or more times
+within an XSUB.
+
+The following examples are equivalent, but if the code is using complex
+typemaps then the first example is safer.
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ PREINIT:
+ char *host = "localhost";
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+For this particular case an INIT: keyword would generate the
+same C code as the PREINIT: keyword. Another correct, but error-prone example:
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ CODE:
+ char *host = "localhost";
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+Another way to declare C<host> is to use a C block in the CODE: section:
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ CODE:
+ {
+ char *host = "localhost";
+ RETVAL = rpcb_gettime( host, &timep );
+ }
+ OUTPUT:
+ timep
+ RETVAL
+
+The ability to put additional declarations before the typemap entries are
+processed is very handy in the cases when typemap conversions manipulate
+some global state:
+
+ MyObject
+ mutate(o)
+ PREINIT:
+ MyState st = global_state;
+ INPUT:
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+Here we suppose that conversion to C<MyObject> in the INPUT: section and from
+MyObject when processing RETVAL will modify a global variable C<global_state>.
+After these conversions are performed, we restore the old value of
+C<global_state> (to avoid memory leaks, for example).
+
+There is another way to trade clarity for compactness: INPUT sections allow
+declaration of C variables which do not appear in the parameter list of
+a subroutine. Thus the above code for mutate() can be rewritten as
+
+ MyObject
+ mutate(o)
+ MyState st = global_state;
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+and the code for rpcb_gettime() can be rewritten as
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ char *host = "localhost";
+ C_ARGS:
+ host, &timep
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 The SCOPE: Keyword
+
+The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
+enabled, the XSUB will invoke ENTER and LEAVE automatically.
+
+To support potentially complex type mappings, if a typemap entry used
+by an XSUB contains a comment like C</*scope*/> then scoping will
+be automatically enabled for that XSUB.
+
+To enable scoping:
+
+ SCOPE: ENABLE
+
+To disable scoping:
+
+ SCOPE: DISABLE
+
+=head2 The INPUT: Keyword
+
+The XSUB's parameters are usually evaluated immediately after entering the
+XSUB. The INPUT: keyword can be used to force those parameters to be
+evaluated a little later. The INPUT: keyword can be used multiple times
+within an XSUB and can be used to list one or more input variables. This
+keyword is used with the PREINIT: keyword.
+
+The following example shows how the input parameter C<timep> can be
+evaluated late, after a PREINIT.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ PREINIT:
+ time_t tt;
+ INPUT:
+ time_t timep
+ CODE:
+ RETVAL = rpcb_gettime( host, &tt );
+ timep = tt;
+ OUTPUT:
+ timep
+ RETVAL
+
+The next example shows each input parameter evaluated late.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ PREINIT:
+ time_t tt;
+ INPUT:
+ char *host
+ PREINIT:
+ char *h;
+ INPUT:
+ time_t timep
+ CODE:
+ h = host;
+ RETVAL = rpcb_gettime( h, &tt );
+ timep = tt;
+ OUTPUT:
+ timep
+ RETVAL
+
+Since INPUT sections allow declaration of C variables which do not appear
+in the parameter list of a subroutine, this may be shortened to:
+
+ bool_t
+ rpcb_gettime(host,timep)
+ time_t tt;
+ char *host;
+ char *h = host;
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( h, &tt );
+ timep = tt;
+ OUTPUT:
+ timep
+ RETVAL
+
+(We used our knowledge that input conversion for C<char *> is a "simple" one,
+thus C<host> is initialized on the declaration line, and our assignment
+C<h = host> is not performed too early. Otherwise one would need to have the
+assignment C<h = host> in a CODE: or INIT: section.)
+
+=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
+
+In the list of parameters for an XSUB, one can precede parameter names
+by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords.
+C<IN> keyword is the default, the other keywords indicate how the Perl
+interface should differ from the C interface.
+
+Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT>
+keywords are considered to be used by the C subroutine I<via
+pointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine
+does not inspect the memory pointed by this parameter, but will write
+through this pointer to provide additional return values.
+
+Parameters preceded by C<OUTLIST> keyword do not appear in the usage
+signature of the generated Perl function.
+
+Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as
+parameters to the Perl function. With the exception of
+C<OUT>-parameters, these parameters are converted to the corresponding
+C type, then pointers to these data are given as arguments to the C
+function. It is expected that the C function will write through these
+pointers.
+
+The return list of the generated Perl function consists of the C return value
+from the function (unless the XSUB is of C<void> return type or
+C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST>
+and C<IN_OUTLIST> parameters (in the order of appearance). On the
+return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be
+modified to have the values written by the C function.
+
+For example, an XSUB
+
+ void
+ day_month(OUTLIST day, IN unix_time, OUTLIST month)
+ int day
+ int unix_time
+ int month
+
+should be used from Perl as
+
+ my ($day, $month) = day_month(time);
+
+The C signature of the corresponding function should be
+
+ void day_month(int *day, int unix_time, int *month);
+
+The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be
+mixed with ANSI-style declarations, as in
+
+ void
+ day_month(OUTLIST int day, int unix_time, OUTLIST int month)
+
+(here the optional C<IN> keyword is omitted).
+
+The C<IN_OUT> parameters are identical with parameters introduced with
+L<The & Unary Operator> and put into the C<OUTPUT:> section (see
+L<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar,
+the only difference being that the value C function writes through the
+pointer would not modify the Perl parameter, but is put in the output
+list.
+
+The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT>
+parameters only by the initial value of the Perl parameter not
+being read (and not being given to the C function - which gets some
+garbage instead). For example, the same C function as above can be
+interfaced with as
+
+ void day_month(OUT int day, int unix_time, OUT int month);
+
+or
+
+ void
+ day_month(day, unix_time, month)
+ int &day = NO_INIT
+ int unix_time
+ int &month = NO_INIT
+ OUTPUT:
+ day
+ month
+
+However, the generated Perl function is called in very C-ish style:
+
+ my ($day, $month);
+ day_month($day, time, $month);
+
+=head2 The C<length(NAME)> Keyword
+
+If one of the input arguments to the C function is the length of a string
+argument C<NAME>, one can substitute the name of the length-argument by
+C<length(NAME)> in the XSUB declaration. This argument must be omitted when
+the generated Perl function is called. E.g.,
+
+ void
+ dump_chars(char *s, short l)
+ {
+ short n = 0;
+ while (n < l) {
+ printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
+ n++;
+ }
+ }
+
+ MODULE = x PACKAGE = x
+
+ void dump_chars(char *s, short length(s))
+
+should be called as C<dump_chars($string)>.
+
+This directive is supported with ANSI-type function declarations only.
+
+=head2 Variable-length Parameter Lists
+
+XSUBs can have variable-length parameter lists by specifying an ellipsis
+C<(...)> in the parameter list. This use of the ellipsis is similar to that
+found in ANSI C. The programmer is able to determine the number of
+arguments passed to the XSUB by examining the C<items> variable which the
+B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
+create an XSUB which accepts a list of parameters of unknown length.
+
+The I<host> parameter for the rpcb_gettime() XSUB can be
+optional so the ellipsis can be used to indicate that the
+XSUB will take a variable number of parameters. Perl should
+be able to call this XSUB with either of the following statements.
+
+ $status = rpcb_gettime( $timep, $host );
+
+ $status = rpcb_gettime( $timep );
+
+The XS code, with ellipsis, follows.
+
+ bool_t
+ rpcb_gettime(timep, ...)
+ time_t timep = NO_INIT
+ PREINIT:
+ char *host = "localhost";
+ CODE:
+ if( items > 1 )
+ host = (char *)SvPVbyte_nolen(ST(1));
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 The C_ARGS: Keyword
+
+The C_ARGS: keyword allows creating of XSUBS which have different
+calling sequence from Perl than from C, without a need to write
+CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
+put as the argument to the called C function without any change.
+
+For example, suppose that a C function is declared as
+
+ symbolic nth_derivative(int n, symbolic function, int flags);
+
+and that the default flags are kept in a global C variable
+C<default_flags>. Suppose that you want to create an interface which
+is called as
+
+ $second_deriv = $function->nth_derivative(2);
+
+To do this, declare the XSUB as
+
+ symbolic
+ nth_derivative(function, n)
+ symbolic function
+ int n
+ C_ARGS:
+ n, function, default_flags
+
+=head2 The PPCODE: Keyword
+
+The PPCODE: keyword is an alternate form of the CODE: keyword and is used
+to tell the B<xsubpp> compiler that the programmer is supplying the code to
+control the argument stack for the XSUBs return values. Occasionally one
+will want an XSUB to return a list of values rather than a single value.
+In these cases one must use PPCODE: and then explicitly push the list of
+values on the stack. The PPCODE: and CODE: keywords should not be used
+together within the same XSUB.
+
+The actual difference between PPCODE: and CODE: sections is in the
+initialization of C<SP> macro (which stands for the I<current> Perl
+stack pointer), and in the handling of data on the stack when returning
+from an XSUB. In CODE: sections SP preserves the value which was on
+entry to the XSUB: SP is on the function pointer (which follows the
+last parameter). In PPCODE: sections SP is moved backward to the
+beginning of the parameter list, which allows C<PUSH*()> macros
+to place output values in the place Perl expects them to be when
+the XSUB returns back to Perl.
+
+The generated trailer for a CODE: section ensures that the number of return
+values Perl will see is either 0 or 1 (depending on the C<void>ness of the
+return value of the C function, and heuristics mentioned in
+L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
+is based on the number of return values and on the number of times
+C<SP> was updated by C<[X]PUSH*()> macros.
+
+Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
+well in CODE: sections and PPCODE: sections.
+
+The following XSUB will call the C rpcb_gettime() function
+and will return its two output values, timep and status, to
+Perl as a single list.
+
+ void
+ rpcb_gettime(host)
+ char *host
+ PREINIT:
+ time_t timep;
+ bool_t status;
+ PPCODE:
+ status = rpcb_gettime( host, &timep );
+ EXTEND(SP, 2);
+ PUSHs(sv_2mortal(newSViv(status)));
+ PUSHs(sv_2mortal(newSViv(timep)));
+
+Notice that the programmer must supply the C code necessary
+to have the real rpcb_gettime() function called and to have
+the return values properly placed on the argument stack.
+
+The C<void> return type for this function tells the B<xsubpp> compiler that
+the RETVAL variable is not needed or used and that it should not be created.
+In most scenarios the void return type should be used with the PPCODE:
+directive.
+
+The EXTEND() macro is used to make room on the argument
+stack for 2 return values. The PPCODE: directive causes the
+B<xsubpp> compiler to create a stack pointer available as C<SP>, and it
+is this pointer which is being used in the EXTEND() macro.
+The values are then pushed onto the stack with the PUSHs()
+macro.
+
+Now the rpcb_gettime() function can be used from Perl with
+the following statement.
+
+ ($status, $timep) = rpcb_gettime("localhost");
+
+When handling output parameters with a PPCODE section, be sure to handle
+'set' magic properly. See L<perlguts> for details about 'set' magic.
+
+=head2 Returning Undef And Empty Lists
+
+Occasionally the programmer will want to return simply
+C<undef> or an empty list if a function fails rather than a
+separate status value. The rpcb_gettime() function offers
+just this situation. If the function succeeds we would like
+to have it return the time and if it fails we would like to
+have undef returned. In the following Perl code the value
+of $timep will either be undef or it will be a valid time.
+
+ $timep = rpcb_gettime( "localhost" );
+
+The following XSUB uses the C<SV *> return type as a mnemonic only,
+and uses a CODE: block to indicate to the compiler
+that the programmer has supplied all the necessary code. The
+sv_newmortal() call will initialize the return value to undef, making that
+the default return value.
+
+ SV *
+ rpcb_gettime(host)
+ char * host
+ PREINIT:
+ time_t timep;
+ bool_t x;
+ CODE:
+ ST(0) = sv_newmortal();
+ if( rpcb_gettime( host, &timep ) )
+ sv_setnv( ST(0), (double)timep);
+
+The next example demonstrates how one would place an explicit undef in the
+return value, should the need arise.
+
+ SV *
+ rpcb_gettime(host)
+ char * host
+ PREINIT:
+ time_t timep;
+ bool_t x;
+ CODE:
+ if( rpcb_gettime( host, &timep ) ){
+ ST(0) = sv_newmortal();
+ sv_setnv( ST(0), (double)timep);
+ }
+ else{
+ ST(0) = &PL_sv_undef;
+ }
+
+To return an empty list one must use a PPCODE: block and
+then not push return values on the stack.
+
+ void
+ rpcb_gettime(host)
+ char *host
+ PREINIT:
+ time_t timep;
+ PPCODE:
+ if( rpcb_gettime( host, &timep ) )
+ PUSHs(sv_2mortal(newSViv(timep)));
+ else{
+ /* Nothing pushed on stack, so an empty
+ * list is implicitly returned. */
+ }
+
+Some people may be inclined to include an explicit C<return> in the above
+XSUB, rather than letting control fall through to the end. In those
+situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
+the XSUB stack is properly adjusted. Consult L<perlapi> for other
+C<XSRETURN> macros.
+
+Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
+rewrite this example as:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ PREINIT:
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+ OUTPUT:
+ RETVAL
+
+In fact, one can put this check into a POSTCALL: section as well. Together
+with PREINIT: simplifications, this leads to:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ time_t timep;
+ POSTCALL:
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+
+=head2 The REQUIRE: Keyword
+
+The REQUIRE: keyword is used to indicate the minimum version of the
+B<xsubpp> compiler needed to compile the XS module. An XS module which
+contains the following statement will compile with only B<xsubpp> version
+1.922 or greater:
+
+ REQUIRE: 1.922
+
+=head2 The CLEANUP: Keyword
+
+This keyword can be used when an XSUB requires special cleanup procedures
+before it terminates. When the CLEANUP: keyword is used it must follow
+any CODE:, or OUTPUT: blocks which are present in the XSUB. The code
+specified for the cleanup block will be added as the last statements in
+the XSUB.
+
+=head2 The POSTCALL: Keyword
+
+This keyword can be used when an XSUB requires special procedures
+executed after the C subroutine call is performed. When the POSTCALL:
+keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
+present in the XSUB.
+
+See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">.
+
+The POSTCALL: block does not make a lot of sense when the C subroutine
+call is supplied by user by providing either CODE: or PPCODE: section.
+
+=head2 The BOOT: Keyword
+
+The BOOT: keyword is used to add code to the extension's bootstrap
+function. The bootstrap function is generated by the B<xsubpp> compiler and
+normally holds the statements necessary to register any XSUBs with Perl.
+With the BOOT: keyword the programmer can tell the compiler to add extra
+statements to the bootstrap function.
+
+This keyword may be used any time after the first MODULE keyword and should
+appear on a line by itself. The first blank line after the keyword will
+terminate the code block.
+
+ BOOT:
+ # The following message will be printed when the
+ # bootstrap function executes.
+ printf("Hello from the bootstrap!\n");
+
+=head2 The VERSIONCHECK: Keyword
+
+The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
+C<-noversioncheck> options. This keyword overrides the command line
+options. Version checking is enabled by default. When version checking is
+enabled the XS module will attempt to verify that its version matches the
+version of the PM module.
+
+To enable version checking:
+
+ VERSIONCHECK: ENABLE
+
+To disable version checking:
+
+ VERSIONCHECK: DISABLE
+
+Note that if the version of the PM module is an NV (a floating point
+number), it will be stringified with a possible loss of precision
+(currently chopping to nine decimal places) so that it may not match
+the version of the XS module anymore. Quoting the $VERSION declaration
+to make it a string is recommended if long version numbers are used.
+
+=head2 The PROTOTYPES: Keyword
+
+The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
+C<-noprototypes> options. This keyword overrides the command line options.
+Prototypes are disabled by default. When prototypes are enabled, XSUBs will
+be given Perl prototypes. This keyword may be used multiple times in an XS
+module to enable and disable prototypes for different parts of the module.
+Note that B<xsubpp> will nag you if you don't explicitly enable or disable
+prototypes, with:
+
+ Please specify prototyping behavior for Foo.xs (see perlxs manual)
+
+To enable prototypes:
+
+ PROTOTYPES: ENABLE
+
+To disable prototypes:
+
+ PROTOTYPES: DISABLE
+
+=head2 The PROTOTYPE: Keyword
+
+This keyword is similar to the PROTOTYPES: keyword above but can be used to
+force B<xsubpp> to use a specific prototype for the XSUB. This keyword
+overrides all other prototype options and keywords but affects only the
+current XSUB. Consult L<perlsub/Prototypes> for information about Perl
+prototypes.
+
+ bool_t
+ rpcb_gettime(timep, ...)
+ time_t timep = NO_INIT
+ PROTOTYPE: $;$
+ PREINIT:
+ char *host = "localhost";
+ CODE:
+ if( items > 1 )
+ host = (char *)SvPVbyte_nolen(ST(1));
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+If the prototypes are enabled, you can disable it locally for a given
+XSUB as in the following example:
+
+ void
+ rpcb_gettime_noproto()
+ PROTOTYPE: DISABLE
+ ...
+
+=head2 The ALIAS: Keyword
+
+The ALIAS: keyword allows an XSUB to have two or more unique Perl names
+and to know which of those names was used when it was invoked. The Perl
+names may be fully-qualified with package names. Each alias is given an
+index. The compiler will setup a variable called C<ix> which contain the
+index of the alias which was used. When the XSUB is called with its
+declared name C<ix> will be 0.
+
+The following example will create aliases C<FOO::gettime()> and
+C<BAR::getit()> for this function.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ ALIAS:
+ FOO::gettime = 1
+ BAR::getit = 2
+ INIT:
+ printf("# ix = %d\n", ix );
+ OUTPUT:
+ timep
+
+A warning will be produced when you create more than one alias to the same
+value. This may be worked around in a backwards compatible way by creating
+multiple defines which resolve to the same value, or with a modern version
+of ExtUtils::ParseXS you can use a symbolic alias, which are denoted with
+a C<< => >> instead of a C<< = >>. For instance you could change the above
+so that the alias section looked like this:
+
+ ALIAS:
+ FOO::gettime = 1
+ BAR::getit = 2
+ BAZ::gettime => FOO::gettime
+
+this would have the same effect as this:
+
+ ALIAS:
+ FOO::gettime = 1
+ BAR::getit = 2
+ BAZ::gettime = 1
+
+except that the latter will produce warnings during the build process. A
+mechanism that would work in a backwards compatible way with older
+versions of our tool chain would be to do this:
+
+ #define FOO_GETTIME 1
+ #define BAR_GETIT 2
+ #define BAZ_GETTIME 1
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ ALIAS:
+ FOO::gettime = FOO_GETTIME
+ BAR::getit = BAR_GETIT
+ BAZ::gettime = BAZ_GETTIME
+ INIT:
+ printf("# ix = %d\n", ix );
+ OUTPUT:
+ timep
+
+=head2 The OVERLOAD: Keyword
+
+Instead of writing an overloaded interface using pure Perl, you
+can also use the OVERLOAD keyword to define additional Perl names
+for your functions (like the ALIAS: keyword above). However, the
+overloaded functions must be defined in such a way as to accept the number
+of parameters supplied by perl's overload system. For most overload
+methods, it will be three parameters; for the C<nomethod> function it will
+be four. However, the bitwise operators C<&>, C<|>, C<^>, and C<~> may be
+called with three I<or> five arguments (see L<overload>).
+
+If any
+function has the OVERLOAD: keyword, several additional lines
+will be defined in the c file generated by xsubpp in order to
+register with the overload magic.
+
+Since blessed objects are actually stored as RV's, it is useful
+to use the typemap features to preprocess parameters and extract
+the actual SV stored within the blessed RV. See the sample for
+T_PTROBJ_SPECIAL below.
+
+To use the OVERLOAD: keyword, create an XS function which takes
+three input parameters (or use the C-style '...' definition) like
+this:
+
+ SV *
+ cmp (lobj, robj, swap)
+ My_Module_obj lobj
+ My_Module_obj robj
+ IV swap
+ OVERLOAD: cmp <=>
+ { /* function defined here */}
+
+In this case, the function will overload both of the three way
+comparison operators. For all overload operations using non-alpha
+characters, you must type the parameter without quoting, separating
+multiple overloads with whitespace. Note that "" (the stringify
+overload) should be entered as \"\" (i.e. escaped).
+
+Since, as mentioned above, bitwise operators may take extra arguments, you
+may want to use something like C<(lobj, robj, swap, ...)> (with
+literal C<...>) as your parameter list.
+
+=head2 The FALLBACK: Keyword
+
+In addition to the OVERLOAD keyword, if you need to control how
+Perl autogenerates missing overloaded operators, you can set the
+FALLBACK keyword in the module header section, like this:
+
+ MODULE = RPC PACKAGE = RPC
+
+ FALLBACK: TRUE
+ ...
+
+where FALLBACK can take any of the three values TRUE, FALSE, or
+UNDEF. If you do not set any FALLBACK value when using OVERLOAD,
+it defaults to UNDEF. FALLBACK is not used except when one or
+more functions using OVERLOAD have been defined. Please see
+L<overload/fallback> for more details.
+
+=head2 The INTERFACE: Keyword
+
+This keyword declares the current XSUB as a keeper of the given
+calling signature. If some text follows this keyword, it is
+considered as a list of functions which have this signature, and
+should be attached to the current XSUB.
+
+For example, if you have 4 C functions multiply(), divide(), add(),
+subtract() all having the signature:
+
+ symbolic f(symbolic, symbolic);
+
+you can make them all to use the same XSUB using this:
+
+ symbolic
+ interface_s_ss(arg1, arg2)
+ symbolic arg1
+ symbolic arg2
+ INTERFACE:
+ multiply divide
+ add subtract
+
+(This is the complete XSUB code for 4 Perl functions!) Four generated
+Perl function share names with corresponding C functions.
+
+The advantage of this approach comparing to ALIAS: keyword is that there
+is no need to code a switch statement, each Perl function (which shares
+the same XSUB) knows which C function it should call. Additionally, one
+can attach an extra function remainder() at runtime by using
+
+ CV *mycv = newXSproto("Symbolic::remainder",
+ XS_Symbolic_interface_s_ss, __FILE__, "$$");
+ XSINTERFACE_FUNC_SET(mycv, remainder);
+
+say, from another XSUB. (This example supposes that there was no
+INTERFACE_MACRO: section, otherwise one needs to use something else instead of
+C<XSINTERFACE_FUNC_SET>, see the next section.)
+
+=head2 The INTERFACE_MACRO: Keyword
+
+This keyword allows one to define an INTERFACE using a different way
+to extract a function pointer from an XSUB. The text which follows
+this keyword should give the name of macros which would extract/set a
+function pointer. The extractor macro is given return type, C<CV*>,
+and C<XSANY.any_dptr> for this C<CV*>. The setter macro is given cv,
+and the function pointer.
+
+The default value is C<XSINTERFACE_FUNC> and C<XSINTERFACE_FUNC_SET>.
+An INTERFACE keyword with an empty list of functions can be omitted if
+INTERFACE_MACRO keyword is used.
+
+Suppose that in the previous example functions pointers for
+multiply(), divide(), add(), subtract() are kept in a global C array
+C<fp[]> with offsets being C<multiply_off>, C<divide_off>, C<add_off>,
+C<subtract_off>. Then one can use
+
+ #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
+ ((XSINTERFACE_CVT_ANON(ret))fp[CvXSUBANY(cv).any_i32])
+ #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
+ CvXSUBANY(cv).any_i32 = CAT2( f, _off )
+
+in C section,
+
+ symbolic
+ interface_s_ss(arg1, arg2)
+ symbolic arg1
+ symbolic arg2
+ INTERFACE_MACRO:
+ XSINTERFACE_FUNC_BYOFFSET
+ XSINTERFACE_FUNC_BYOFFSET_set
+ INTERFACE:
+ multiply divide
+ add subtract
+
+in XSUB section.
+
+=head2 The INCLUDE: Keyword
+
+This keyword can be used to pull other files into the XS module. The other
+files may have XS code. INCLUDE: can also be used to run a command to
+generate the XS code to be pulled into the module.
+
+The file F<Rpcb1.xsh> contains our C<rpcb_gettime()> function:
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ OUTPUT:
+ timep
+
+The XS module can use INCLUDE: to pull that file into it.
+
+ INCLUDE: Rpcb1.xsh
+
+If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
+the compiler will interpret the parameters as a command. This feature is
+mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
+below.
+
+ INCLUDE: cat Rpcb1.xsh |
+
+Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
+happens to be the first in your path and not necessarily the same perl that is
+used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
+
+=head2 The INCLUDE_COMMAND: Keyword
+
+Runs the supplied command and includes its output into the current XS
+document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
+in that it runs the same perl interpreter that is running C<xsubpp>:
+
+ INCLUDE_COMMAND: cat Rpcb1.xsh
+
+ INCLUDE_COMMAND: $^X -e ...
+
+=head2 The CASE: Keyword
+
+The CASE: keyword allows an XSUB to have multiple distinct parts with each
+part acting as a virtual XSUB. CASE: is greedy and if it is used then all
+other XS keywords must be contained within a CASE:. This means nothing may
+precede the first CASE: in the XSUB and anything following the last CASE: is
+included in that case.
+
+A CASE: might switch via a parameter of the XSUB, via the C<ix> ALIAS:
+variable (see L<"The ALIAS: Keyword">), or maybe via the C<items> variable
+(see L<"Variable-length Parameter Lists">). The last CASE: becomes the
+B<default> case if it is not associated with a conditional. The following
+example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
+having an alias C<x_gettime()>. When the function is called as
+C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
+but when the function is called as C<x_gettime()> its parameters are
+reversed, C<(time_t *timep, char *host)>.
+
+ long
+ rpcb_gettime(a,b)
+ CASE: ix == 1
+ ALIAS:
+ x_gettime = 1
+ INPUT:
+ # 'a' is timep, 'b' is host
+ char *b
+ time_t a = NO_INIT
+ CODE:
+ RETVAL = rpcb_gettime( b, &a );
+ OUTPUT:
+ a
+ RETVAL
+ CASE:
+ # 'a' is host, 'b' is timep
+ char *a
+ time_t &b = NO_INIT
+ OUTPUT:
+ b
+ RETVAL
+
+That function can be called with either of the following statements. Note
+the different argument lists.
+
+ $status = rpcb_gettime( $host, $timep );
+
+ $status = x_gettime( $timep, $host );
+
+=head2 The EXPORT_XSUB_SYMBOLS: Keyword
+
+The EXPORT_XSUB_SYMBOLS: keyword is likely something you will never need.
+In perl versions earlier than 5.16.0, this keyword does nothing. Starting
+with 5.16, XSUB symbols are no longer exported by default. That is, they
+are C<static> functions. If you include
+
+ EXPORT_XSUB_SYMBOLS: ENABLE
+
+in your XS code, the XSUBs following this line will not be declared C<static>.
+You can later disable this with
+
+ EXPORT_XSUB_SYMBOLS: DISABLE
+
+which, again, is the default that you should probably never change.
+You cannot use this keyword on versions of perl before 5.16 to make
+XSUBs C<static>.
+
+=head2 The & Unary Operator
+
+The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
+that it should convert a Perl value to/from C using the C type to the left
+of C<&>, but provide a pointer to this value when the C function is called.
+
+This is useful to avoid a CODE: block for a C function which takes a parameter
+by reference. Typically, the parameter should be not a pointer type (an
+C<int> or C<long> but not an C<int*> or C<long*>).
+
+The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
+turn this into code which calls C<rpcb_gettime()> with parameters C<(char
+*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
+parameter to be of type C<time_t*> rather than C<time_t>.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t timep
+ OUTPUT:
+ timep
+
+That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
+will now turn this into code which calls C<rpcb_gettime()> correctly with
+parameters C<(char *host, time_t *timep)>. It does this by carrying the
+C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char *host
+ time_t &timep
+ OUTPUT:
+ timep
+
+=head2 Inserting POD, Comments and C Preprocessor Directives
+
+C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
+PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
+Comments are allowed anywhere after the MODULE keyword. The compiler will
+pass the preprocessor directives through untouched and will remove the
+commented lines. POD documentation is allowed at any point, both in the
+C and XS language sections. POD must be terminated with a C<=cut> command;
+C<xsubpp> will exit with an error if it does not. It is very unlikely that
+human generated C code will be mistaken for POD, as most indenting styles
+result in whitespace in front of any line starting with C<=>. Machine
+generated XS files may fall into this trap unless care is taken to
+ensure that a space breaks the sequence "\n=".
+
+Comments can be added to XSUBs by placing a C<#> as the first
+non-whitespace of a line. Care should be taken to avoid making the
+comment look like a C preprocessor directive, lest it be interpreted as
+such. The simplest way to prevent this is to put whitespace in front of
+the C<#>.
+
+If you use preprocessor directives to choose one of two
+versions of a function, use
+
+ #if ... version1
+ #else /* ... version2 */
+ #endif
+
+and not
+
+ #if ... version1
+ #endif
+ #if ... version2
+ #endif
+
+because otherwise B<xsubpp> will believe that you made a duplicate
+definition of the function. Also, put a blank line before the
+#else/#endif so it will not be seen as part of the function body.
+
+=head2 Using XS With C++
+
+If an XSUB name contains C<::>, it is considered to be a C++ method.
+The generated Perl function will assume that
+its first argument is an object pointer. The object pointer
+will be stored in a variable called THIS. The object should
+have been created by C++ with the new() function and should
+be blessed by Perl with the sv_setref_pv() macro. The
+blessing of the object by Perl can be handled by a typemap. An example
+typemap is shown at the end of this section.
+
+If the return type of the XSUB includes C<static>, the method is considered
+to be a static method. It will call the C++
+function using the class::method() syntax. If the method is not static
+the function will be called using the THIS-E<gt>method() syntax.
+
+The next examples will use the following C++ class.
+
+ class color {
+ public:
+ color();
+ ~color();
+ int blue();
+ void set_blue( int );
+
+ private:
+ int c_blue;
+ };
+
+The XSUBs for the blue() and set_blue() methods are defined with the class
+name but the parameter for the object (THIS, or "self") is implicit and is
+not listed.
+
+ int
+ color::blue()
+
+ void
+ color::set_blue( val )
+ int val
+
+Both Perl functions will expect an object as the first parameter. In the
+generated C++ code the object is called C<THIS>, and the method call will
+be performed on this object. So in the C++ code the blue() and set_blue()
+methods will be called as this:
+
+ RETVAL = THIS->blue();
+
+ THIS->set_blue( val );
+
+You could also write a single get/set method using an optional argument:
+
+ int
+ color::blue( val = NO_INIT )
+ int val
+ PROTOTYPE $;$
+ CODE:
+ if (items > 1)
+ THIS->set_blue( val );
+ RETVAL = THIS->blue();
+ OUTPUT:
+ RETVAL
+
+If the function's name is B<DESTROY> then the C++ C<delete> function will be
+called and C<THIS> will be given as its parameter. The generated C++ code for
+
+ void
+ color::DESTROY()
+
+will look like this:
+
+ color *THIS = ...; // Initialized as in typemap
+
+ delete THIS;
+
+If the function's name is B<new> then the C++ C<new> function will be called
+to create a dynamic C++ object. The XSUB will expect the class name, which
+will be kept in a variable called C<CLASS>, to be given as the first
+argument.
+
+ color *
+ color::new()
+
+The generated C++ code will call C<new>.
+
+ RETVAL = new color();
+
+The following is an example of a typemap that could be used for this C++
+example.
+
+ TYPEMAP
+ color * O_OBJECT
+
+ OUTPUT
+ # The Perl object is blessed into 'CLASS', which should be a
+ # char* having the name of the package for the blessing.
+ O_OBJECT
+ sv_setref_pv( $arg, CLASS, (void*)$var );
+
+ INPUT
+ O_OBJECT
+ if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
+ $var = ($type)SvIV((SV*)SvRV( $arg ));
+ else{
+ warn(\"${Package}::$func_name() -- \"
+ \"$var is not a blessed SV reference\");
+ XSRETURN_UNDEF;
+ }
+
+=head2 Interface Strategy
+
+When designing an interface between Perl and a C library a straight
+translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
+However, sometimes the interface will look
+very C-like and occasionally nonintuitive, especially when the C function
+modifies one of its parameters, or returns failure inband (as in "negative
+return values mean failure"). In cases where the programmer wishes to
+create a more Perl-like interface the following strategy may help to
+identify the more critical parts of the interface.
+
+Identify the C functions with input/output or output parameters. The XSUBs for
+these functions may be able to return lists to Perl.
+
+Identify the C functions which use some inband info as an indication
+of failure. They may be
+candidates to return undef or an empty list in case of failure. If the
+failure may be detected without a call to the C function, you may want to use
+an INIT: section to report the failure. For failures detectable after the C
+function returns one may want to use a POSTCALL: section to process the
+failure. In more complicated cases use CODE: or PPCODE: sections.
+
+If many functions use the same failure indication based on the return value,
+you may want to create a special typedef to handle this situation. Put
+
+ typedef int negative_is_failure;
+
+near the beginning of XS file, and create an OUTPUT typemap entry
+for C<negative_is_failure> which converts negative values to C<undef>, or
+maybe croak()s. After this the return value of type C<negative_is_failure>
+will create more Perl-like interface.
+
+Identify which values are used by only the C and XSUB functions
+themselves, say, when a parameter to a function should be a contents of a
+global variable. If Perl does not need to access the contents of the value
+then it may not be necessary to provide a translation for that value
+from C to Perl.
+
+Identify the pointers in the C function parameter lists and return
+values. Some pointers may be used to implement input/output or
+output parameters, they can be handled in XS with the C<&> unary operator,
+and, possibly, using the NO_INIT keyword.
+Some others will require handling of types like C<int *>, and one needs
+to decide what a useful Perl translation will do in such a case. When
+the semantic is clear, it is advisable to put the translation into a typemap
+file.
+
+Identify the structures used by the C functions. In many
+cases it may be helpful to use the T_PTROBJ typemap for
+these structures so they can be manipulated by Perl as
+blessed objects. (This is handled automatically by C<h2xs -x>.)
+
+If the same C type is used in several different contexts which require
+different translations, C<typedef> several new types mapped to this C type,
+and create separate F<typemap> entries for these new types. Use these
+types in declarations of return type and parameters to XSUBs.
+
+=head2 Perl Objects And C Structures
+
+When dealing with C structures one should select either
+B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
+designed to handle pointers to complex objects. The
+T_PTRREF type will allow the Perl object to be unblessed
+while the T_PTROBJ type requires that the object be blessed.
+By using T_PTROBJ one can achieve a form of type-checking
+because the XSUB will attempt to verify that the Perl object
+is of the expected type.
+
+The following XS code shows the getnetconfigent() function which is used
+with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a
+C structure and has the C prototype shown below. The example will
+demonstrate how the C pointer will become a Perl reference. Perl will
+consider this reference to be a pointer to a blessed object and will
+attempt to call a destructor for the object. A destructor will be
+provided in the XS source to free the memory used by getnetconfigent().
+Destructors in XS can be created by specifying an XSUB function whose name
+ends with the word B<DESTROY>. XS destructors can be used to free memory
+which may have been malloc'd by another XSUB.
+
+ struct netconfig *getnetconfigent(const char *netid);
+
+A C<typedef> will be created for C<struct netconfig>. The Perl
+object will be blessed in a class matching the name of the C
+type, with the tag C<Ptr> appended, and the name should not
+have embedded spaces if it will be a Perl package name. The
+destructor will be placed in a class corresponding to the
+class of the object and the PREFIX keyword will be used to
+trim the name to the word DESTROY as Perl will expect.
+
+ typedef struct netconfig Netconfig;
+
+ MODULE = RPC PACKAGE = RPC
+
+ Netconfig *
+ getnetconfigent(netid)
+ char *netid
+
+ MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
+
+ void
+ rpcb_DESTROY(netconf)
+ Netconfig *netconf
+ CODE:
+ printf("Now in NetconfigPtr::DESTROY\n");
+ free( netconf );
+
+This example requires the following typemap entry. Consult
+L<perlxstypemap> for more information about adding new typemaps
+for an extension.
+
+ TYPEMAP
+ Netconfig * T_PTROBJ
+
+This example will be used with the following Perl statements.
+
+ use RPC;
+ $netconf = getnetconfigent("udp");
+
+When Perl destroys the object referenced by $netconf it will send the
+object to the supplied XSUB DESTROY function. Perl cannot determine, and
+does not care, that this object is a C struct and not a Perl object. In
+this sense, there is no difference between the object created by the
+getnetconfigent() XSUB and an object created by a normal Perl subroutine.
+
+=head2 Safely Storing Static Data in XS
+
+Starting with Perl 5.8, a macro framework has been defined to allow
+static data to be safely stored in XS modules that will be accessed from
+a multi-threaded Perl.
+
+Although primarily designed for use with multi-threaded Perl, the macros
+have been designed so that they will work with non-threaded Perl as well.
+
+It is therefore strongly recommended that these macros be used by all
+XS modules that make use of static data.
+
+The easiest way to get a template set of macros to use is by specifying
+the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
+
+Below is an example module that makes use of the macros.
+
+ #define PERL_NO_GET_CONTEXT
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ /* Global Data */
+
+ #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
+
+ typedef struct {
+ int count;
+ char name[3][100];
+ } my_cxt_t;
+
+ START_MY_CXT
+
+ MODULE = BlindMice PACKAGE = BlindMice
+
+ BOOT:
+ {
+ MY_CXT_INIT;
+ MY_CXT.count = 0;
+ strcpy(MY_CXT.name[0], "None");
+ strcpy(MY_CXT.name[1], "None");
+ strcpy(MY_CXT.name[2], "None");
+ }
+
+ int
+ newMouse(char * name)
+ PREINIT:
+ dMY_CXT;
+ CODE:
+ if (MY_CXT.count >= 3) {
+ warn("Already have 3 blind mice");
+ RETVAL = 0;
+ }
+ else {
+ RETVAL = ++ MY_CXT.count;
+ strcpy(MY_CXT.name[MY_CXT.count - 1], name);
+ }
+ OUTPUT:
+ RETVAL
+
+ char *
+ get_mouse_name(index)
+ int index
+ PREINIT:
+ dMY_CXT;
+ CODE:
+ if (index > MY_CXT.count)
+ croak("There are only 3 blind mice.");
+ else
+ RETVAL = MY_CXT.name[index - 1];
+ OUTPUT:
+ RETVAL
+
+ void
+ CLONE(...)
+ CODE:
+ MY_CXT_CLONE;
+
+=head3 MY_CXT REFERENCE
+
+=over 5
+
+=item MY_CXT_KEY
+
+This macro is used to define a unique key to refer to the static data
+for an XS module. The suggested naming scheme, as used by h2xs, is to
+use a string that consists of the module name, the string "::_guts"
+and the module version number.
+
+ #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
+
+=item typedef my_cxt_t
+
+This struct typedef I<must> always be called C<my_cxt_t>. The other
+C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
+
+Declare a typedef named C<my_cxt_t> that is a structure that contains
+all the data that needs to be interpreter-local.
+
+ typedef struct {
+ int some_value;
+ } my_cxt_t;
+
+=item START_MY_CXT
+
+Always place the START_MY_CXT macro directly after the declaration
+of C<my_cxt_t>.
+
+=for apidoc Amnh||START_MY_CXT
+
+=item MY_CXT_INIT
+
+The MY_CXT_INIT macro initializes storage for the C<my_cxt_t> struct.
+
+It I<must> be called exactly once, typically in a BOOT: section. If you
+are maintaining multiple interpreters, it should be called once in each
+interpreter instance, except for interpreters cloned from existing ones.
+(But see L</MY_CXT_CLONE> below.)
+
+=for apidoc Amnh||MY_CXT_INIT
+
+=item dMY_CXT
+
+Use the dMY_CXT macro (a declaration) in all the functions that access
+MY_CXT.
+
+=for apidoc Amnh||dMY_CXT
+
+=item MY_CXT
+
+Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
+example, if C<my_cxt_t> is
+
+ typedef struct {
+ int index;
+ } my_cxt_t;
+
+then use this to access the C<index> member
+
+ dMY_CXT;
+ MY_CXT.index = 2;
+
+=item aMY_CXT/pMY_CXT
+
+C<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead
+of invoking it in each function it is possible to pass the declaration
+onto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg
+
+=for apidoc Amnh||_aMY_CXT
+=for apidoc Amnh||aMY_CXT
+=for apidoc Amnh||aMY_CXT_
+=for apidoc Amnh||_pMY_CXT
+=for apidoc Amnh||pMY_CXT
+=for apidoc Amnh||pMY_CXT_
+=for apidoc Amnh||MY_CXT
+
+ void sub1() {
+ dMY_CXT;
+ MY_CXT.index = 1;
+ sub2(aMY_CXT);
+ }
+
+ void sub2(pMY_CXT) {
+ MY_CXT.index = 2;
+ }
+
+Analogously to C<pTHX>, there are equivalent forms for when the macro is the
+first or last in multiple arguments, where an underscore represents a
+comma, i.e. C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>.
+
+=item MY_CXT_CLONE
+
+By default, when a new interpreter is created as a copy of an existing one
+(eg via C<< threads->create() >>), both interpreters share the same physical
+my_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's
+C<CLONE()> function), causes a byte-for-byte copy of the structure to be
+taken, and any future dMY_CXT will cause the copy to be accessed instead.
+
+=for apidoc Amnh||MY_CXT_CLONE
+
+=item MY_CXT_INIT_INTERP(my_perl)
+
+=item dMY_CXT_INTERP(my_perl)
+
+These are versions of the macros which take an explicit interpreter as an
+argument.
+
+=back
+
+Note that these macros will only work together within the I<same> source
+file; that is, a dMY_CTX in one source file will access a different structure
+than a dMY_CTX in another source file.
+
+=head2 Thread-aware system interfaces
+
+Starting from Perl 5.8, in C/C++ level Perl knows how to wrap
+system/library interfaces that have thread-aware versions
+(e.g. getpwent_r()) into frontend macros (e.g. getpwent()) that
+correctly handle the multithreaded interaction with the Perl
+interpreter. This will happen transparently, the only thing
+you need to do is to instantiate a Perl interpreter.
+
+This wrapping happens always when compiling Perl core source
+(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
+defined). When compiling XS code outside of the Perl core, the wrapping
+does not take place before Perl 5.28. Starting in that release you can
+
+ #define PERL_REENTRANT
+
+in your code to enable the wrapping. It is advisable to do so if you
+are using such functions, as intermixing the C<_r>-forms (as Perl compiled
+for multithreaded operation will do) and the C<_r>-less forms is neither
+well-defined (inconsistent results, data corruption, or even crashes
+become more likely), nor is it very portable. Unfortunately, not all
+systems have all the C<_r> forms, but using this C<#define> gives you
+whatever protection that Perl is aware is available on each system.
+
+=head1 EXAMPLES
+
+File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
+
+ #define PERL_NO_GET_CONTEXT
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ /* Note: On glibc 2.13 and earlier, this needs be <rpc/rpc.h> */
+ #include <tirpc/rpc.h>
+
+ typedef struct netconfig Netconfig;
+
+ MODULE = RPC PACKAGE = RPC
+
+ SV *
+ rpcb_gettime(host="localhost")
+ char *host
+ PREINIT:
+ time_t timep;
+ CODE:
+ ST(0) = sv_newmortal();
+ if( rpcb_gettime( host, &timep ) )
+ sv_setnv( ST(0), (double)timep );
+
+ Netconfig *
+ getnetconfigent(netid="udp")
+ char *netid
+
+ MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
+
+ void
+ rpcb_DESTROY(netconf)
+ Netconfig *netconf
+ CODE:
+ printf("NetconfigPtr::DESTROY\n");
+ free( netconf );
+
+File C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>)
+
+ TYPEMAP
+ Netconfig * T_PTROBJ
+
+File C<RPC.pm>: Perl module for the RPC extension.
+
+ package RPC;
+
+ require Exporter;
+ require DynaLoader;
+ @ISA = qw(Exporter DynaLoader);
+ @EXPORT = qw(rpcb_gettime getnetconfigent);
+
+ bootstrap RPC;
+ 1;
+
+File C<rpctest.pl>: Perl test program for the RPC extension.
+
+ use RPC;
+
+ $netconf = getnetconfigent();
+ $a = rpcb_gettime();
+ print "time = $a\n";
+ print "netconf = $netconf\n";
+
+ $netconf = getnetconfigent("tcp");
+ $a = rpcb_gettime("poplar");
+ print "time = $a\n";
+ print "netconf = $netconf\n";
+
+In Makefile.PL add -ltirpc and -I/usr/include/tirpc.
+
+=head1 CAVEATS
+
+XS code has full access to system calls including C library functions.
+It thus has the capability of interfering with things that the Perl core
+or other modules have set up, such as signal handlers or file handles.
+It could mess with the memory, or any number of harmful things. Don't.
+
+Some modules have an event loop, waiting for user-input. It is highly
+unlikely that two such modules would work adequately together in a
+single Perl application.
+
+In general, the perl interpreter views itself as the center of the
+universe as far as the Perl program goes. XS code is viewed as a
+help-mate, to accomplish things that perl doesn't do, or doesn't do fast
+enough, but always subservient to perl. The closer XS code adheres to
+this model, the less likely conflicts will occur.
+
+One area where there has been conflict is in regards to C locales. (See
+L<perllocale>.) perl, with one exception and unless told otherwise,
+sets up the underlying locale the program is running in to the locale
+passed
+into it from the environment. This is an important difference from a
+generic C language program, where the underlying locale is the "C"
+locale unless the program changes it. As of v5.20, this underlying
+locale is completely hidden from pure Perl code outside the lexical
+scope of C<S<use locale>> except for a couple of function calls in the
+POSIX module which of necessity use it. But the underlying locale, with
+that
+one exception is exposed to XS code, affecting all C library routines
+whose behavior is locale-dependent. Your XS code better not assume that
+the underlying locale is "C". The exception is the
+L<C<LC_NUMERIC>|perllocale/Category LC_NUMERIC: Numeric Formatting>
+locale category, and the reason it is an exception is that experience
+has shown that it can be problematic for XS code, whereas we have not
+had reports of problems with the
+L<other locale categories|perllocale/WHAT IS A LOCALE>. And the reason
+for this one category being problematic is that the character used as a
+decimal point can vary. Many European languages use a comma, whereas
+English, and hence Perl are expecting a dot (U+002E: FULL STOP). Many
+modules can handle only the radix character being a dot, and so perl
+attempts to make it so. Up through Perl v5.20, the attempt was merely
+to set C<LC_NUMERIC> upon startup to the C<"C"> locale. Any
+L<setlocale()|perllocale/The setlocale function> otherwise would change
+it; this caused some failures. Therefore, starting in v5.22, perl tries
+to keep C<LC_NUMERIC> always set to C<"C"> for XS code.
+
+To summarize, here's what to expect and how to handle locales in XS code:
+
+=over
+
+=item Non-locale-aware XS code
+
+Keep in mind that even if you think your code is not locale-aware, it
+may call a library function that is. Hopefully the man page for such
+a function will indicate that dependency, but the documentation is
+imperfect.
+
+The current locale is exposed to XS code except possibly C<LC_NUMERIC>
+(explained in the next paragraph).
+There have not been reports of problems with the other categories.
+Perl initializes things on start-up so that the current locale is the
+one which is indicated by the user's environment in effect at that time.
+See L<perllocale/ENVIRONMENT>.
+
+However, up through v5.20, Perl initialized things on start-up so that
+C<LC_NUMERIC> was set to the "C" locale. But if any code anywhere
+changed it, it would stay changed. This means that your module can't
+count on C<LC_NUMERIC> being something in particular, and you can't
+expect floating point numbers (including version strings) to have dots
+in them. If you don't allow for a non-dot, your code could break if
+anyone anywhere changed the locale. For this reason, v5.22 changed
+the behavior so that Perl tries to keep C<LC_NUMERIC> in the "C" locale
+except around the operations internally where it should be something
+else. Misbehaving XS code will always be able to change the locale
+anyway, but the most common instance of this is checked for and
+handled.
+
+=item Locale-aware XS code
+
+If the locale from the user's environment is desired, there should be no
+need for XS code to set the locale except for C<LC_NUMERIC>, as perl has
+already set the others up. XS code should avoid changing the locale, as
+it can adversely affect other, unrelated, code and may not be
+thread-safe. To minimize problems, the macros
+L<perlapi/STORE_LC_NUMERIC_SET_TO_NEEDED>,
+L<perlapi/STORE_LC_NUMERIC_FORCE_TO_UNDERLYING>, and
+L<perlapi/RESTORE_LC_NUMERIC> should be used to affect any needed
+change.
+
+But, starting with Perl v5.28, locales are thread-safe on platforms that
+support this functionality. Windows has this starting with Visual
+Studio 2005. Many other modern platforms support the thread-safe POSIX
+2008 functions. The C C<#define> C<USE_THREAD_SAFE_LOCALE> will be
+defined iff this build is using these. From Perl-space, the read-only
+variable C<${SAFE_LOCALES}> is 1 if either the build is not threaded, or
+if C<USE_THREAD_SAFE_LOCALE> is defined; otherwise it is 0.
+
+The way this works under-the-hood is that every thread has a choice of
+using a locale specific to it (this is the Windows and POSIX 2008
+functionality), or the global locale that is accessible to all threads
+(this is the functionality that has always been there). The
+implementations for Windows and POSIX are completely different. On
+Windows, the runtime can be set up so that the standard
+L<C<setlocale(3)>> function either only knows about the global locale or
+the locale for this thread. On POSIX, C<setlocale> always deals with
+the global locale, and other functions have been created to handle
+per-thread locales. Perl makes this transparent to perl-space code. It
+continues to use C<POSIX::setlocale()>, and the interpreter translates
+that into the per-thread functions.
+
+All other locale-sensitive functions automatically use the per-thread
+locale, if that is turned on, and failing that, the global locale. Thus
+calls to C<setlocale> are ineffective on POSIX systems for the current
+thread if that thread is using a per-thread locale. If perl is compiled
+for single-thread operation, it does not use the per-thread functions,
+so C<setlocale> does work as expected.
+
+If you have loaded the L<C<POSIX>> module you can use the methods given
+in L<perlcall> to call L<C<POSIX::setlocale>|POSIX/setlocale> to safely
+change or query the locale (on systems where it is safe to do so), or
+you can use the new 5.28 function L<perlapi/Perl_setlocale> instead,
+which is a drop-in replacement for the system L<C<setlocale(3)>>, and
+handles single-threaded and multi-threaded applications transparently.
+
+There are some locale-related library calls that still aren't
+thread-safe because they return data in a buffer global to all threads.
+In the past, these didn't matter as locales weren't thread-safe at all.
+But now you have to be aware of them in case your module is called in a
+multi-threaded application. The known ones are
+
+ asctime()
+ ctime()
+ gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
+ getdate()
+ wcrtomb() if its final argument is NULL
+ wcsrtombs() if its final argument is NULL
+ wcstombs()
+ wctomb()
+
+Some of these shouldn't really be called in a Perl application, and for
+others there are thread-safe versions of these already implemented:
+
+ asctime_r()
+ ctime_r()
+ Perl_langinfo()
+
+The C<_r> forms are automatically used, starting in Perl 5.28, if you
+compile your code, with
+
+ #define PERL_REENTRANT
+
+See also L<perlapi/Perl_langinfo>.
+You can use the methods given in L<perlcall>, to get the best available
+locale-safe versions of these
+
+ POSIX::localeconv()
+ POSIX::wcstombs()
+ POSIX::wctomb()
+
+And note, that some items returned by C<Localeconv> are available
+through L<perlapi/Perl_langinfo>.
+
+The others shouldn't be used in a threaded application.
+
+Some modules may call a non-perl library that is locale-aware. This is
+fine as long as it doesn't try to query or change the locale using the
+system C<setlocale>. But if these do call the system C<setlocale>,
+those calls may be ineffective. Instead,
+L<C<Perl_setlocale>|perlapi/Perl_setlocale> works in all circumstances.
+Plain setlocale is ineffective on multi-threaded POSIX 2008 systems. It
+operates only on the global locale, whereas each thread has its own
+locale, paying no attention to the global one. Since converting
+these non-Perl libraries to C<Perl_setlocale> is out of the question,
+there is a new function in v5.28
+L<C<switch_to_global_locale>|perlapi/switch_to_global_locale> that will
+switch the thread it is called from so that any system C<setlocale>
+calls will have their desired effect. The function
+L<C<sync_locale>|perlapi/sync_locale> must be called before returning to
+perl.
+
+This thread can change the locale all it wants and it won't affect any
+other thread, except any that also have been switched to the global
+locale. This means that a multi-threaded application can have a single
+thread using an alien library without a problem; but no more than a
+single thread can be so-occupied. Bad results likely will happen.
+
+In perls without multi-thread locale support, some alien libraries,
+such as C<Gtk> change locales. This can cause problems for the Perl
+core and other modules. For these, before control is returned to
+perl, starting in v5.20.1, calling the function
+L<sync_locale()|perlapi/sync_locale> from XS should be sufficient to
+avoid most of these problems. Prior to this, you need a pure Perl
+statement that does this:
+
+ POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
+
+or use the methods given in L<perlcall>.
+
+=back
+
+=head1 XS VERSION
+
+This document covers features supported by C<ExtUtils::ParseXS>
+(also known as C<xsubpp>) 3.51
+
+=head1 AUTHOR DIAGNOSTICS
+
+As of version 3.49 certain warnings are disabled by default. While developing
+you can set C<$ENV{AUTHOR_WARNINGS}> to true in your environment or in your
+Makefile.PL, or set C<$ExtUtils::ParseXS::AUTHOR_WARNINGS> to true via code, or
+pass C<< author_warnings=>1 >> into process_file() explicitly. Currently this will
+enable stricter alias checking but more warnings might be added in the future.
+The kind of warnings this will enable are only helpful to the author of the XS
+file, and the diagnostics produced will not include installation specific
+details so they are only useful to the maintainer of the XS code itself.
+
+=head1 AUTHOR
+
+Originally written by Dean Roehrich <F<roehrich@cray.com>>.
+
+Maintained since 1996 by The Perl Porters <F<perl5-porters@perl.org>>.
diff --git a/lib/perlxstut.pod b/lib/perlxstut.pod
new file mode 100644
index 0000000..fcafa58
--- /dev/null
+++ b/lib/perlxstut.pod
@@ -0,0 +1,1425 @@
+=head1 NAME
+
+perlxstut - Tutorial for writing XSUBs
+
+=head1 DESCRIPTION
+
+This tutorial will educate the reader on the steps involved in creating
+a Perl extension. The reader is assumed to have access to L<perlguts>,
+L<perlapi> and L<perlxs>.
+
+This tutorial starts with very simple examples and becomes more complex,
+with each new example adding new features. Certain concepts may not be
+completely explained until later in the tutorial in order to slowly ease
+the reader into building extensions.
+
+This tutorial was written from a Unix point of view. Where I know them
+to be otherwise different for other platforms (e.g. Win32), I will list
+them. If you find something that was missed, please let me know.
+
+=head1 SPECIAL NOTES
+
+=head2 make
+
+This tutorial assumes that the make program that Perl is configured to
+use is called C<make>. Instead of running "make" in the examples that
+follow, you may have to substitute whatever make program Perl has been
+configured to use. Running B<perl -V:make> should tell you what it is.
+
+=head2 Version caveat
+
+When writing a Perl extension for general consumption, one should expect that
+the extension will be used with versions of Perl different from the
+version available on your machine. Since you are reading this document,
+the version of Perl on your machine is probably 5.005 or later, but the users
+of your extension may have more ancient versions.
+
+To understand what kinds of incompatibilities one may expect, and in the rare
+case that the version of Perl on your machine is older than this document,
+see the section on "Troubleshooting these Examples" for more information.
+
+If your extension uses some features of Perl which are not available on older
+releases of Perl, your users would appreciate an early meaningful warning.
+You would probably put this information into the F<README> file, but nowadays
+installation of extensions may be performed automatically, guided by F<CPAN.pm>
+module or other tools.
+
+In MakeMaker-based installations, F<Makefile.PL> provides the earliest
+opportunity to perform version checks. One can put something like this
+in F<Makefile.PL> for this purpose:
+
+ eval { require 5.007 }
+ or die <<EOD;
+ ############
+ ### This module uses frobnication framework which is not available
+ ### before version 5.007 of Perl. Upgrade your Perl before
+ ### installing Kara::Mba.
+ ############
+ EOD
+
+=head2 Dynamic Loading versus Static Loading
+
+It is commonly thought that if a system does not have the capability to
+dynamically load a library, you cannot build XSUBs. This is incorrect.
+You I<can> build them, but you must link the XSUBs subroutines with the
+rest of Perl, creating a new executable. This situation is similar to
+Perl 4.
+
+This tutorial can still be used on such a system. The XSUB build mechanism
+will check the system and build a dynamically-loadable library if possible,
+or else a static library and then, optionally, a new statically-linked
+executable with that static library linked in.
+
+Should you wish to build a statically-linked executable on a system which
+can dynamically load libraries, you may, in all the following examples,
+where the command "C<make>" with no arguments is executed, run the command
+"C<make perl>" instead.
+
+If you have generated such a statically-linked executable by choice, then
+instead of saying "C<make test>", you should say "C<make test_static>".
+On systems that cannot build dynamically-loadable libraries at all, simply
+saying "C<make test>" is sufficient.
+
+=head2 Threads and PERL_NO_GET_CONTEXT
+
+For threaded builds, perl requires the context pointer for the current
+thread, without C<PERL_NO_GET_CONTEXT>, perl will call a function to
+retrieve the context.
+
+For improved performance, include:
+
+ #define PERL_NO_GET_CONTEXT
+
+as shown below.
+
+For more details, see L<perlguts|perlguts/How multiple interpreters
+and concurrency are supported>.
+
+=head1 TUTORIAL
+
+Now let's go on with the show!
+
+=head2 EXAMPLE 1
+
+Our first extension will be very simple. When we call the routine in the
+extension, it will print out a well-known message and return.
+
+Run "C<h2xs -A -n Mytest>". This creates a directory named Mytest,
+possibly under ext/ if that directory exists in the current working
+directory. Several files will be created under the Mytest dir, including
+MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, and Changes.
+
+The MANIFEST file contains the names of all the files just created in the
+Mytest directory.
+
+The file Makefile.PL should look something like this:
+
+ use ExtUtils::MakeMaker;
+
+ # See lib/ExtUtils/MakeMaker.pm for details of how to influence
+ # the contents of the Makefile that is written.
+ WriteMakefile(
+ NAME => 'Mytest',
+ VERSION_FROM => 'Mytest.pm', # finds $VERSION
+ LIBS => [''], # e.g., '-lm'
+ DEFINE => '', # e.g., '-DHAVE_SOMETHING'
+ INC => '-I', # e.g., '-I. -I/usr/include/other'
+ );
+
+The file Mytest.pm should start with something like this:
+
+ package Mytest;
+
+ use 5.008008;
+ use strict;
+ use warnings;
+
+ require Exporter;
+
+ our @ISA = qw(Exporter);
+ our %EXPORT_TAGS = ( 'all' => [ qw(
+
+ ) ] );
+
+ our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
+
+ our @EXPORT = qw(
+
+ );
+
+ our $VERSION = '0.01';
+
+ require XSLoader;
+ XSLoader::load('Mytest', $VERSION);
+
+ # Preloaded methods go here.
+
+ 1;
+ __END__
+ # Below is the stub of documentation for your module. You better
+ # edit it!
+
+The rest of the .pm file contains sample code for providing documentation for
+the extension.
+
+Finally, the Mytest.xs file should look something like this:
+
+ #define PERL_NO_GET_CONTEXT
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ #include "ppport.h"
+
+ MODULE = Mytest PACKAGE = Mytest
+
+Let's edit the .xs file by adding this to the end of the file:
+
+ void
+ hello()
+ CODE:
+ printf("Hello, world!\n");
+
+It is okay for the lines starting at the "CODE:" line to not be indented.
+However, for readability purposes, it is suggested that you indent CODE:
+one level and the lines following one more level.
+
+Now we'll run "C<perl Makefile.PL>". This will create a real Makefile,
+which make needs. Its output looks something like:
+
+ % perl Makefile.PL
+ Checking if your kit is complete...
+ Looks good
+ Writing Makefile for Mytest
+ %
+
+Now, running make will produce output that looks something like this (some
+long lines have been shortened for clarity and some extraneous lines have
+been deleted):
+
+ % make
+ cp lib/Mytest.pm blib/lib/Mytest.pm
+ perl xsubpp -typemap typemap Mytest.xs > Mytest.xsc && \
+ mv Mytest.xsc Mytest.c
+ Please specify prototyping behavior for Mytest.xs (see perlxs manual)
+ cc -c Mytest.c
+ Running Mkbootstrap for Mytest ()
+ chmod 644 Mytest.bs
+ rm -f blib/arch/auto/Mytest/Mytest.so
+ cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so
+
+ chmod 755 blib/arch/auto/Mytest/Mytest.so
+ cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
+ chmod 644 blib/arch/auto/Mytest/Mytest.bs
+ Manifying blib/man3/Mytest.3pm
+ %
+
+You can safely ignore the line about "prototyping behavior" - it is
+explained in L<perlxs/"The PROTOTYPES: Keyword">.
+
+Perl has its own special way of easily writing test scripts, but for this
+example only, we'll create our own test script. Create a file called hello
+that looks like this:
+
+ #! /opt/perl5/bin/perl
+
+ use ExtUtils::testlib;
+
+ use Mytest;
+
+ Mytest::hello();
+
+Now we make the script executable (C<chmod +x hello>), run the script
+and we should see the following output:
+
+ % ./hello
+ Hello, world!
+ %
+
+=head2 EXAMPLE 2
+
+Now let's add to our extension a subroutine that will take a single numeric
+argument as input and return 1 if the number is even or 0 if the number
+is odd.
+
+Add the following to the end of Mytest.xs:
+
+ int
+ is_even(input)
+ int input
+ CODE:
+ RETVAL = (input % 2 == 0);
+ OUTPUT:
+ RETVAL
+
+There does not need to be whitespace at the start of the "C<int input>"
+line, but it is useful for improving readability. Placing a semi-colon at
+the end of that line is also optional. Any amount and kind of whitespace
+may be placed between the "C<int>" and "C<input>".
+
+Now re-run make to rebuild our new shared library.
+
+Now perform the same steps as before, generating a Makefile from the
+Makefile.PL file, and running make.
+
+In order to test that our extension works, we now need to look at the
+file Mytest.t. This file is set up to imitate the same kind of testing
+structure that Perl itself has. Within the test script, you perform a
+number of tests to confirm the behavior of the extension, printing "ok"
+when the test is correct, "not ok" when it is not.
+
+ use Test::More tests => 4;
+ BEGIN { use_ok('Mytest') };
+
+ #########################
+
+ # Insert your test code below, the Test::More module is use()ed here
+ # so read its man page ( perldoc Test::More ) for help writing this
+ # test script.
+
+ is( Mytest::is_even(0), 1 );
+ is( Mytest::is_even(1), 0 );
+ is( Mytest::is_even(2), 1 );
+
+We will be calling the test script through the command "C<make test>". You
+should see output that looks something like this:
+
+ %make test
+ PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e"
+ "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
+ t/Mytest....ok
+ All tests successful.
+ Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU)
+ %
+
+=head2 What has gone on?
+
+The program h2xs is the starting point for creating extensions. In later
+examples we'll see how we can use h2xs to read header files and generate
+templates to connect to C routines.
+
+h2xs creates a number of files in the extension directory. The file
+Makefile.PL is a perl script which will generate a true Makefile to build
+the extension. We'll take a closer look at it later.
+
+The .pm and .xs files contain the meat of the extension. The .xs file holds
+the C routines that make up the extension. The .pm file contains routines
+that tell Perl how to load your extension.
+
+Generating the Makefile and running C<make> created a directory called blib
+(which stands for "build library") in the current working directory. This
+directory will contain the shared library that we will build. Once we have
+tested it, we can install it into its final location.
+
+Invoking the test script via "C<make test>" did something very important.
+It invoked perl with all those C<-I> arguments so that it could find the
+various files that are part of the extension. It is I<very> important that
+while you are still testing extensions that you use "C<make test>". If you
+try to run the test script all by itself, you will get a fatal error.
+Another reason it is important to use "C<make test>" to run your test
+script is that if you are testing an upgrade to an already-existing version,
+using "C<make test>" ensures that you will test your new extension, not the
+already-existing version.
+
+When Perl sees a C<use extension;>, it searches for a file with the same name
+as the C<use>'d extension that has a .pm suffix. If that file cannot be found,
+Perl dies with a fatal error. The default search path is contained in the
+C<@INC> array.
+
+In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic
+Loader extensions. It then sets the C<@ISA> and C<@EXPORT> arrays and the
+C<$VERSION> scalar; finally it tells perl to bootstrap the module. Perl
+will call its dynamic loader routine (if there is one) and load the shared
+library.
+
+The two arrays C<@ISA> and C<@EXPORT> are very important. The C<@ISA>
+array contains a list of other packages in which to search for methods (or
+subroutines) that do not exist in the current package. This is usually
+only important for object-oriented extensions (which we will talk about
+much later), and so usually doesn't need to be modified.
+
+The C<@EXPORT> array tells Perl which of the extension's variables and
+subroutines should be placed into the calling package's namespace. Because
+you don't know if the user has already used your variable and subroutine
+names, it's vitally important to carefully select what to export. Do I<not>
+export method or variable names I<by default> without a good reason.
+
+As a general rule, if the module is trying to be object-oriented then don't
+export anything. If it's just a collection of functions and variables, then
+you can export them via another array, called C<@EXPORT_OK>. This array
+does not automatically place its subroutine and variable names into the
+namespace unless the user specifically requests that this be done.
+
+See L<perlmod> for more information.
+
+The C<$VERSION> variable is used to ensure that the .pm file and the shared
+library are "in sync" with each other. Any time you make changes to
+the .pm or .xs files, you should increment the value of this variable.
+
+=head2 Writing good test scripts
+
+The importance of writing good test scripts cannot be over-emphasized. You
+should closely follow the "ok/not ok" style that Perl itself uses, so that
+it is very easy and unambiguous to determine the outcome of each test case.
+When you find and fix a bug, make sure you add a test case for it.
+
+By running "C<make test>", you ensure that your Mytest.t script runs and uses
+the correct version of your extension. If you have many test cases,
+save your test files in the "t" directory and use the suffix ".t".
+When you run "C<make test>", all of these test files will be executed.
+
+=head2 EXAMPLE 3
+
+Our third extension will take one argument as its input, round off that
+value, and set the I<argument> to the rounded value.
+
+Add the following to the end of Mytest.xs:
+
+ void
+ round(arg)
+ double arg
+ CODE:
+ if (arg > 0.0) {
+ arg = floor(arg + 0.5);
+ } else if (arg < 0.0) {
+ arg = ceil(arg - 0.5);
+ } else {
+ arg = 0.0;
+ }
+ OUTPUT:
+ arg
+
+Edit the Makefile.PL file so that the corresponding line looks like this:
+
+ LIBS => ['-lm'], # e.g., '-lm'
+
+Generate the Makefile and run make. Change the test number in Mytest.t to
+"9" and add the following tests:
+
+ my $i;
+
+ $i = -1.5;
+ Mytest::round($i);
+ is( $i, -2.0, 'Rounding -1.5 to -2.0' );
+
+ $i = -1.1;
+ Mytest::round($i);
+ is( $i, -1.0, 'Rounding -1.1 to -1.0' );
+
+ $i = 0.0;
+ Mytest::round($i);
+ is( $i, 0.0, 'Rounding 0.0 to 0.0' );
+
+ $i = 0.5;
+ Mytest::round($i);
+ is( $i, 1.0, 'Rounding 0.5 to 1.0' );
+
+ $i = 1.2;
+ Mytest::round($i);
+ is( $i, 1.0, 'Rounding 1.2 to 1.0' );
+
+Running "C<make test>" should now print out that all nine tests are okay.
+
+Notice that in these new test cases, the argument passed to round was a
+scalar variable. You might be wondering if you can round a constant or
+literal. To see what happens, temporarily add the following line to Mytest.t:
+
+ Mytest::round(3);
+
+Run "C<make test>" and notice that Perl dies with a fatal error. Perl won't
+let you change the value of constants!
+
+=head2 What's new here?
+
+=over 4
+
+=item *
+
+We've made some changes to Makefile.PL. In this case, we've specified an
+extra library to be linked into the extension's shared library, the math
+library libm in this case. We'll talk later about how to write XSUBs that
+can call every routine in a library.
+
+=item *
+
+The value of the function is not being passed back as the function's return
+value, but by changing the value of the variable that was passed into the
+function. You might have guessed that when you saw that the return value
+of round is of type "void".
+
+=back
+
+=head2 Input and Output Parameters
+
+You specify the parameters that will be passed into the XSUB on the line(s)
+after you declare the function's return value and name. Each input parameter
+line starts with optional whitespace, and may have an optional terminating
+semicolon.
+
+The list of output parameters occurs at the very end of the function, just
+after the OUTPUT: directive. The use of RETVAL tells Perl that you
+wish to send this value back as the return value of the XSUB function. In
+Example 3, we wanted the "return value" placed in the original variable
+which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section.
+
+=head2 The XSUBPP Program
+
+The B<xsubpp> program takes the XS code in the .xs file and translates it into
+C code, placing it in a file whose suffix is .c. The C code created makes
+heavy use of the C functions within Perl.
+
+=head2 The TYPEMAP file
+
+The B<xsubpp> program uses rules to convert from Perl's data types (scalar,
+array, etc.) to C's data types (int, char, etc.). These rules are stored
+in the typemap file ($PERLLIB/ExtUtils/typemap). There's a brief discussion
+below, but all the nitty-gritty details can be found in L<perlxstypemap>.
+If you have a new-enough version of perl (5.16 and up) or an upgraded
+XS compiler (C<ExtUtils::ParseXS> 3.13_01 or better), then you can inline
+typemaps in your XS instead of writing separate files.
+Either way, this typemap thing is split into three parts:
+
+The first section maps various C data types to a name, which corresponds
+somewhat with the various Perl types. The second section contains C code
+which B<xsubpp> uses to handle input parameters. The third section contains
+C code which B<xsubpp> uses to handle output parameters.
+
+Let's take a look at a portion of the .c file created for our extension.
+The file name is Mytest.c:
+
+ XS(XS_Mytest_round)
+ {
+ dXSARGS;
+ if (items != 1)
+ Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
+ PERL_UNUSED_VAR(cv); /* -W */
+ {
+ double arg = (double)SvNV(ST(0)); /* XXXXX */
+ if (arg > 0.0) {
+ arg = floor(arg + 0.5);
+ } else if (arg < 0.0) {
+ arg = ceil(arg - 0.5);
+ } else {
+ arg = 0.0;
+ }
+ sv_setnv(ST(0), (double)arg); /* XXXXX */
+ SvSETMAGIC(ST(0));
+ }
+ XSRETURN_EMPTY;
+ }
+
+Notice the two lines commented with "XXXXX". If you check the first part
+of the typemap file (or section), you'll see that doubles are of type
+T_DOUBLE. In the INPUT part of the typemap, an argument that is T_DOUBLE
+is assigned to the variable arg by calling the routine SvNV on something,
+then casting it to double, then assigned to the variable arg. Similarly,
+in the OUTPUT section, once arg has its final value, it is passed to the
+sv_setnv function to be passed back to the calling subroutine. These two
+functions are explained in L<perlguts>; we'll talk more later about what
+that "ST(0)" means in the section on the argument stack.
+
+=head2 Warning about Output Arguments
+
+In general, it's not a good idea to write extensions that modify their input
+parameters, as in Example 3. Instead, you should probably return multiple
+values in an array and let the caller handle them (we'll do this in a later
+example). However, in order to better accommodate calling pre-existing C
+routines, which often do modify their input parameters, this behavior is
+tolerated.
+
+=head2 EXAMPLE 4
+
+In this example, we'll now begin to write XSUBs that will interact with
+pre-defined C libraries. To begin with, we will build a small library of
+our own, then let h2xs write our .pm and .xs files for us.
+
+Create a new directory called Mytest2 at the same level as the directory
+Mytest. In the Mytest2 directory, create another directory called mylib,
+and cd into that directory.
+
+Here we'll create some files that will generate a test library. These will
+include a C source file and a header file. We'll also create a Makefile.PL
+in this directory. Then we'll make sure that running make at the Mytest2
+level will automatically run this Makefile.PL file and the resulting Makefile.
+
+In the mylib directory, create a file mylib.h that looks like this:
+
+ #define TESTVAL 4
+
+ extern double foo(int, long, const char*);
+
+Also create a file mylib.c that looks like this:
+
+ #include <stdlib.h>
+ #include "mylib.h"
+
+ double
+ foo(int a, long b, const char *c)
+ {
+ return (a + b + atof(c) + TESTVAL);
+ }
+
+And finally create a file Makefile.PL that looks like this:
+
+ use ExtUtils::MakeMaker;
+ $Verbose = 1;
+ WriteMakefile(
+ NAME => 'Mytest2::mylib',
+ SKIP => [qw(all static static_lib dynamic dynamic_lib)],
+ clean => {'FILES' => 'libmylib$(LIB_EXT)'},
+ );
+
+
+ sub MY::top_targets {
+ '
+ all :: static
+
+ pure_all :: static
+
+ static :: libmylib$(LIB_EXT)
+
+ libmylib$(LIB_EXT): $(O_FILES)
+ $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
+ $(RANLIB) libmylib$(LIB_EXT)
+
+ ';
+ }
+
+Make sure you use a tab and not spaces on the lines beginning with "$(AR)"
+and "$(RANLIB)". Make will not function properly if you use spaces.
+It has also been reported that the "cr" argument to $(AR) is unnecessary
+on Win32 systems.
+
+We will now create the main top-level Mytest2 files. Change to the directory
+above Mytest2 and run the following command:
+
+ % h2xs -O -n Mytest2 Mytest2/mylib/mylib.h
+
+This will print out a warning about overwriting Mytest2, but that's okay.
+Our files are stored in Mytest2/mylib, and will be untouched.
+
+The normal Makefile.PL that h2xs generates doesn't know about the mylib
+directory. We need to tell it that there is a subdirectory and that we
+will be generating a library in it. Let's add the argument MYEXTLIB to
+the WriteMakefile call so that it looks like this:
+
+ WriteMakefile(
+ NAME => 'Mytest2',
+ VERSION_FROM => 'Mytest2.pm', # finds $VERSION
+ LIBS => [''], # e.g., '-lm'
+ DEFINE => '', # e.g., '-DHAVE_SOMETHING'
+ INC => '', # e.g., '-I/usr/include/other'
+ MYEXTLIB => 'mylib/libmylib$(LIB_EXT)',
+ );
+
+and then at the end add a subroutine (which will override the pre-existing
+subroutine). Remember to use a tab character to indent the line beginning
+with "cd"!
+
+ sub MY::postamble {
+ '
+ $(MYEXTLIB): mylib/Makefile
+ cd mylib && $(MAKE) $(PASSTHRU)
+ ';
+ }
+
+Let's also fix the MANIFEST file by appending the following three lines:
+
+ mylib/Makefile.PL
+ mylib/mylib.c
+ mylib/mylib.h
+
+To keep our namespace nice and unpolluted, edit the .pm file and change
+the variable C<@EXPORT> to C<@EXPORT_OK>. Finally, in the
+.xs file, edit the #include line to read:
+
+ #include "mylib/mylib.h"
+
+And also add the following function definition to the end of the .xs file:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+ OUTPUT:
+ RETVAL
+
+Now we also need to create a typemap because the default Perl doesn't
+currently support the C<const char *> type. Include a new TYPEMAP
+section in your XS code before the above function:
+
+ TYPEMAP: <<END
+ const char * T_PV
+ END
+
+Now run perl on the top-level Makefile.PL. Notice that it also created a
+Makefile in the mylib directory. Run make and watch that it does cd into
+the mylib directory and run make in there as well.
+
+Now edit the Mytest2.t script and change the number of tests to "5",
+and add the following lines to the end of the script:
+
+ is( Mytest2::foo( 1, 2, "Hello, world!" ), 7 );
+ is( Mytest2::foo( 1, 2, "0.0" ), 7 );
+ ok( abs( Mytest2::foo( 0, 0, "-3.4" ) - 0.6 ) <= 0.01 );
+
+(When dealing with floating-point comparisons, it is best to not check for
+equality, but rather that the difference between the expected and actual
+result is below a certain amount (called epsilon) which is 0.01 in this case)
+
+Run "C<make test>" and all should be well. There are some warnings on missing
+tests for the Mytest2::mylib extension, but you can ignore them.
+
+=head2 What has happened here?
+
+Unlike previous examples, we've now run h2xs on a real include file. This
+has caused some extra goodies to appear in both the .pm and .xs files.
+
+=over 4
+
+=item *
+
+In the .xs file, there's now a #include directive with the absolute path to
+the mylib.h header file. We changed this to a relative path so that we
+could move the extension directory if we wanted to.
+
+=item *
+
+There's now some new C code that's been added to the .xs file. The purpose
+of the C<constant> routine is to make the values that are #define'd in the
+header file accessible by the Perl script (by calling either C<TESTVAL> or
+C<&Mytest2::TESTVAL>). There's also some XS code to allow calls to the
+C<constant> routine.
+
+=item *
+
+The .pm file originally exported the name C<TESTVAL> in the C<@EXPORT> array.
+This could lead to name clashes. A good rule of thumb is that if the #define
+is only going to be used by the C routines themselves, and not by the user,
+they should be removed from the C<@EXPORT> array. Alternately, if you don't
+mind using the "fully qualified name" of a variable, you could move most
+or all of the items from the C<@EXPORT> array into the C<@EXPORT_OK> array.
+
+=item *
+
+If our include file had contained #include directives, these would not have
+been processed by h2xs. There is no good solution to this right now.
+
+=item *
+
+We've also told Perl about the library that we built in the mylib
+subdirectory. That required only the addition of the C<MYEXTLIB> variable
+to the WriteMakefile call and the replacement of the postamble subroutine
+to cd into the subdirectory and run make. The Makefile.PL for the
+library is a bit more complicated, but not excessively so. Again we
+replaced the postamble subroutine to insert our own code. This code
+simply specified that the library to be created here was a static archive
+library (as opposed to a dynamically loadable library) and provided the
+commands to build it.
+
+=back
+
+=head2 Anatomy of .xs file
+
+The .xs file of L</EXAMPLE 4> contained some new elements. To understand
+the meaning of these elements, pay attention to the line which reads
+
+ MODULE = Mytest2 PACKAGE = Mytest2
+
+Anything before this line is plain C code which describes which headers
+to include, and defines some convenience functions. No translations are
+performed on this part, apart from having embedded POD documentation
+skipped over (see L<perlpod>) it goes into the generated output C file as is.
+
+Anything after this line is the description of XSUB functions.
+These descriptions are translated by B<xsubpp> into C code which
+implements these functions using Perl calling conventions, and which
+makes these functions visible from Perl interpreter.
+
+Pay a special attention to the function C<constant>. This name appears
+twice in the generated .xs file: once in the first part, as a static C
+function, then another time in the second part, when an XSUB interface to
+this static C function is defined.
+
+This is quite typical for .xs files: usually the .xs file provides
+an interface to an existing C function. Then this C function is defined
+somewhere (either in an external library, or in the first part of .xs file),
+and a Perl interface to this function (i.e. "Perl glue") is described in the
+second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">,
+and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is
+somewhat of an exception rather than the rule.
+
+=head2 Getting the fat out of XSUBs
+
+In L</EXAMPLE 4> the second part of .xs file contained the following
+description of an XSUB:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+ OUTPUT:
+ RETVAL
+
+Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">,
+this description does not contain the actual I<code> for what is done
+during a call to Perl function foo(). To understand what is going
+on here, one can add a CODE section to this XSUB:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+ CODE:
+ RETVAL = foo(a,b,c);
+ OUTPUT:
+ RETVAL
+
+However, these two XSUBs provide almost identical generated C code: B<xsubpp>
+compiler is smart enough to figure out the C<CODE:> section from the first
+two lines of the description of XSUB. What about C<OUTPUT:> section? In
+fact, that is absolutely the same! The C<OUTPUT:> section can be removed
+as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not
+specified: B<xsubpp> can see that it needs to generate a function call
+section, and will autogenerate the OUTPUT section too. Thus one can
+shortcut the XSUB to become:
+
+ double
+ foo(a,b,c)
+ int a
+ long b
+ const char * c
+
+Can we do the same with an XSUB
+
+ int
+ is_even(input)
+ int input
+ CODE:
+ RETVAL = (input % 2 == 0);
+ OUTPUT:
+ RETVAL
+
+of L<"EXAMPLE 2">? To do this, one needs to define a C function C<int
+is_even(int input)>. As we saw in L<Anatomy of .xs file>, a proper place
+for this definition is in the first part of .xs file. In fact a C function
+
+ int
+ is_even(int arg)
+ {
+ return (arg % 2 == 0);
+ }
+
+is probably overkill for this. Something as simple as a C<#define> will
+do too:
+
+ #define is_even(arg) ((arg) % 2 == 0)
+
+After having this in the first part of .xs file, the "Perl glue" part becomes
+as simple as
+
+ int
+ is_even(input)
+ int input
+
+This technique of separation of the glue part from the workhorse part has
+obvious tradeoffs: if you want to change a Perl interface, you need to
+change two places in your code. However, it removes a lot of clutter,
+and makes the workhorse part independent from idiosyncrasies of Perl calling
+convention. (In fact, there is nothing Perl-specific in the above description,
+a different version of B<xsubpp> might have translated this to TCL glue or
+Python glue as well.)
+
+=head2 More about XSUB arguments
+
+With the completion of Example 4, we now have an easy way to simulate some
+real-life libraries whose interfaces may not be the cleanest in the world.
+We shall now continue with a discussion of the arguments passed to the
+B<xsubpp> compiler.
+
+When you specify arguments to routines in the .xs file, you are really
+passing three pieces of information for each argument listed. The first
+piece is the order of that argument relative to the others (first, second,
+etc). The second is the type of argument, and consists of the type
+declaration of the argument (e.g., int, char*, etc). The third piece is
+the calling convention for the argument in the call to the library function.
+
+While Perl passes arguments to functions by reference,
+C passes arguments by value; to implement a C function which modifies data
+of one of the "arguments", the actual argument of this C function would be
+a pointer to the data. Thus two C functions with declarations
+
+ int string_length(char *s);
+ int upper_case_char(char *cp);
+
+may have completely different semantics: the first one may inspect an array
+of chars pointed by s, and the second one may immediately dereference C<cp>
+and manipulate C<*cp> only (using the return value as, say, a success
+indicator). From Perl one would use these functions in
+a completely different manner.
+
+One conveys this info to B<xsubpp> by replacing C<*> before the
+argument by C<&>. C<&> means that the argument should be passed to a library
+function by its address. The above two function may be XSUB-ified as
+
+ int
+ string_length(s)
+ char * s
+
+ int
+ upper_case_char(cp)
+ char &cp
+
+For example, consider:
+
+ int
+ foo(a,b)
+ char &a
+ char * b
+
+The first Perl argument to this function would be treated as a char and
+assigned to the variable a, and its address would be passed into the function
+foo. The second Perl argument would be treated as a string pointer and assigned
+to the variable b. The I<value> of b would be passed into the function foo.
+The actual call to the function foo that B<xsubpp> generates would look like
+this:
+
+ foo(&a, b);
+
+B<xsubpp> will parse the following function argument lists identically:
+
+ char &a
+ char&a
+ char & a
+
+However, to help ease understanding, it is suggested that you place a "&"
+next to the variable name and away from the variable type), and place a
+"*" near the variable type, but away from the variable name (as in the
+call to foo above). By doing so, it is easy to understand exactly what
+will be passed to the C function; it will be whatever is in the "last
+column".
+
+You should take great pains to try to pass the function the type of variable
+it wants, when possible. It will save you a lot of trouble in the long run.
+
+=head2 The Argument Stack
+
+If we look at any of the C code generated by any of the examples except
+example 1, you will notice a number of references to ST(n), where n is
+usually 0. "ST" is actually a macro that points to the n'th argument
+on the argument stack. ST(0) is thus the first argument on the stack and
+therefore the first argument passed to the XSUB, ST(1) is the second
+argument, and so on.
+
+When you list the arguments to the XSUB in the .xs file, that tells B<xsubpp>
+which argument corresponds to which of the argument stack (i.e., the first
+one listed is the first argument, and so on). You invite disaster if you
+do not list them in the same order as the function expects them.
+
+The actual values on the argument stack are pointers to the values passed
+in. When an argument is listed as being an OUTPUT value, its corresponding
+value on the stack (i.e., ST(0) if it was the first argument) is changed.
+You can verify this by looking at the C code generated for Example 3.
+The code for the round() XSUB routine contains lines that look like this:
+
+ double arg = (double)SvNV(ST(0));
+ /* Round the contents of the variable arg */
+ sv_setnv(ST(0), (double)arg);
+
+The arg variable is initially set by taking the value from ST(0), then is
+stored back into ST(0) at the end of the routine.
+
+XSUBs are also allowed to return lists, not just scalars. This must be
+done by manipulating stack values ST(0), ST(1), etc, in a subtly
+different way. See L<perlxs> for details.
+
+XSUBs are also allowed to avoid automatic conversion of Perl function arguments
+to C function arguments. See L<perlxs> for details. Some people prefer
+manual conversion by inspecting C<ST(i)> even in the cases when automatic
+conversion will do, arguing that this makes the logic of an XSUB call clearer.
+Compare with L<"Getting the fat out of XSUBs"> for a similar tradeoff of
+a complete separation of "Perl glue" and "workhorse" parts of an XSUB.
+
+While experts may argue about these idioms, a novice to Perl guts may
+prefer a way which is as little Perl-guts-specific as possible, meaning
+automatic conversion and automatic call generation, as in
+L<"Getting the fat out of XSUBs">. This approach has the additional
+benefit of protecting the XSUB writer from future changes to the Perl API.
+
+=head2 Extending your Extension
+
+Sometimes you might want to provide some extra methods or subroutines
+to assist in making the interface between Perl and your extension simpler
+or easier to understand. These routines should live in the .pm file.
+Whether they are automatically loaded when the extension itself is loaded
+or only loaded when called depends on where in the .pm file the subroutine
+definition is placed. You can also consult L<AutoLoader> for an alternate
+way to store and load your extra subroutines.
+
+=head2 Documenting your Extension
+
+There is absolutely no excuse for not documenting your extension.
+Documentation belongs in the .pm file. This file will be fed to pod2man,
+and the embedded documentation will be converted to the manpage format,
+then placed in the blib directory. It will be copied to Perl's
+manpage directory when the extension is installed.
+
+You may intersperse documentation and Perl code within the .pm file.
+In fact, if you want to use method autoloading, you must do this,
+as the comment inside the .pm file explains.
+
+See L<perlpod> for more information about the pod format.
+
+=head2 Installing your Extension
+
+Once your extension is complete and passes all its tests, installing it
+is quite simple: you simply run "make install". You will either need
+to have write permission into the directories where Perl is installed,
+or ask your system administrator to run the make for you.
+
+Alternately, you can specify the exact directory to place the extension's
+files by placing a "PREFIX=/destination/directory" after the make install
+(or in between the make and install if you have a brain-dead version of make).
+This can be very useful if you are building an extension that will eventually
+be distributed to multiple systems. You can then just archive the files in
+the destination directory and distribute them to your destination systems.
+
+=head2 EXAMPLE 5
+
+In this example, we'll do some more work with the argument stack. The
+previous examples have all returned only a single value. We'll now
+create an extension that returns an array.
+
+This extension is very Unix-oriented (struct statfs and the statfs system
+call). If you are not running on a Unix system, you can substitute for
+statfs any other function that returns multiple values, you can hard-code
+values to be returned to the caller (although this will be a bit harder
+to test the error case), or you can simply not do this example. If you
+change the XSUB, be sure to fix the test cases to match the changes.
+
+Return to the Mytest directory and add the following code to the end of
+Mytest.xs:
+
+ void
+ statfs(path)
+ char * path
+ INIT:
+ int i;
+ struct statfs buf;
+
+ PPCODE:
+ i = statfs(path, &buf);
+ if (i == 0) {
+ XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
+ XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
+ } else {
+ XPUSHs(sv_2mortal(newSVnv(errno)));
+ }
+
+You'll also need to add the following code to the top of the .xs file, just
+after the include of "XSUB.h":
+
+ #include <sys/vfs.h>
+
+Also add the following code segment to Mytest.t while incrementing the "9"
+tests to "11":
+
+ my @a;
+
+ @a = Mytest::statfs("/blech");
+ ok( scalar(@a) == 1 && $a[0] == 2 );
+
+ @a = Mytest::statfs("/");
+ is( scalar(@a), 7 );
+
+=head2 New Things in this Example
+
+This example added quite a few new concepts. We'll take them one at a time.
+
+=over 4
+
+=item *
+
+The INIT: directive contains code that will be placed immediately after
+the argument stack is decoded. C does not allow variable declarations at
+arbitrary locations inside a function,
+so this is usually the best way to declare local variables needed by the XSUB.
+(Alternatively, one could put the whole C<PPCODE:> section into braces, and
+put these declarations on top.)
+
+=item *
+
+This routine also returns a different number of arguments depending on the
+success or failure of the call to statfs. If there is an error, the error
+number is returned as a single-element array. If the call is successful,
+then a 7-element array is returned. Since only one argument is passed into
+this function, we need room on the stack to hold the 7 values which may be
+returned.
+
+We do this by using the PPCODE: directive, rather than the CODE: directive.
+This tells B<xsubpp> that we will be managing the return values that will be
+put on the argument stack by ourselves.
+
+=item *
+
+When we want to place values to be returned to the caller onto the stack,
+we use the series of macros that begin with "XPUSH". There are five
+different versions, for placing integers, unsigned integers, doubles,
+strings, and Perl scalars on the stack. In our example, we placed a
+Perl scalar onto the stack. (In fact this is the only macro which
+can be used to return multiple values.)
+
+The XPUSH* macros will automatically extend the return stack to prevent
+it from being overrun. You push values onto the stack in the order you
+want them seen by the calling program.
+
+=item *
+
+The values pushed onto the return stack of the XSUB are actually mortal SV's.
+They are made mortal so that once the values are copied by the calling
+program, the SV's that held the returned values can be deallocated.
+If they were not mortal, then they would continue to exist after the XSUB
+routine returned, but would not be accessible. This is a memory leak.
+
+=item *
+
+If we were interested in performance, not in code compactness, in the success
+branch we would not use C<XPUSHs> macros, but C<PUSHs> macros, and would
+pre-extend the stack before pushing the return values:
+
+ EXTEND(SP, 7);
+
+The tradeoff is that one needs to calculate the number of return values
+in advance (though overextending the stack will not typically hurt
+anything but memory consumption).
+
+Similarly, in the failure branch we could use C<PUSHs> I<without> extending
+the stack: the Perl function reference comes to an XSUB on the stack, thus
+the stack is I<always> large enough to take one return value.
+
+=back
+
+=head2 EXAMPLE 6
+
+In this example, we will accept a reference to an array as an input
+parameter, and return a reference to an array of hashes. This will
+demonstrate manipulation of complex Perl data types from an XSUB.
+
+This extension is somewhat contrived. It is based on the code in
+the previous example. It calls the statfs function multiple times,
+accepting a reference to an array of filenames as input, and returning
+a reference to an array of hashes containing the data for each of the
+filesystems.
+
+Return to the Mytest directory and add the following code to the end of
+Mytest.xs:
+
+ SV *
+ multi_statfs(paths)
+ SV * paths
+ INIT:
+ AV * results;
+ SSize_t numpaths = 0, n;
+ int i;
+ struct statfs buf;
+
+ SvGETMAGIC(paths);
+ if ((!SvROK(paths))
+ || (SvTYPE(SvRV(paths)) != SVt_PVAV)
+ || ((numpaths = av_top_index((AV *)SvRV(paths))) < 0))
+ {
+ XSRETURN_UNDEF;
+ }
+ results = (AV *)sv_2mortal((SV *)newAV());
+ CODE:
+ for (n = 0; n <= numpaths; n++) {
+ HV * rh;
+ STRLEN l;
+ SV * path = *av_fetch((AV *)SvRV(paths), n, 0);
+ char * fn = SvPVbyte(path, l);
+
+ i = statfs(fn, &buf);
+ if (i != 0) {
+ av_push(results, newSVnv(errno));
+ continue;
+ }
+
+ rh = (HV *)sv_2mortal((SV *)newHV());
+
+ hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
+ hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0);
+ hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
+ hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0);
+ hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0);
+ hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0);
+ hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0);
+
+ av_push(results, newRV_inc((SV *)rh));
+ }
+ RETVAL = newRV_inc((SV *)results);
+ OUTPUT:
+ RETVAL
+
+And add the following code to Mytest.t, while incrementing the "11"
+tests to "13":
+
+ my $results = Mytest::multi_statfs([ '/', '/blech' ]);
+ ok( ref $results->[0] );
+ ok( ! ref $results->[1] );
+
+=head2 New Things in this Example
+
+There are a number of new concepts introduced here, described below:
+
+=over 4
+
+=item *
+
+This function does not use a typemap. Instead, we declare it as accepting
+one SV* (scalar) parameter, and returning an SV* value, and we take care of
+populating these scalars within the code. Because we are only returning
+one value, we don't need a C<PPCODE:> directive - instead, we use C<CODE:>
+and C<OUTPUT:> directives.
+
+=item *
+
+When dealing with references, it is important to handle them with caution.
+The C<INIT:> block first calls SvGETMAGIC(paths), in case
+paths is a tied variable. Then it checks that C<SvROK> returns
+true, which indicates that paths is a valid reference. (Simply
+checking C<SvROK> won't trigger FETCH on a tied variable.) It
+then verifies that the object referenced by paths is an array, using C<SvRV>
+to dereference paths, and C<SvTYPE> to discover its type. As an added test,
+it checks that the array referenced by paths is non-empty, using the
+C<av_top_index> function (which returns -1 if the array is empty). The
+XSRETURN_UNDEF macro is used to abort the XSUB and return the undefined value
+whenever all three of these conditions are not met.
+
+=item *
+
+We manipulate several arrays in this XSUB. Note that an array is represented
+internally by an AV* pointer. The functions and macros for manipulating
+arrays are similar to the functions in Perl: C<av_top_index> returns the
+highest index in an AV*, much like $#array; C<av_fetch> fetches a single scalar
+value from an array, given its index; C<av_push> pushes a scalar value onto the
+end of the array, automatically extending the array as necessary.
+
+Specifically, we read pathnames one at a time from the input array, and
+store the results in an output array (results) in the same order. If
+statfs fails, the element pushed onto the return array is the value of
+errno after the failure. If statfs succeeds, though, the value pushed
+onto the return array is a reference to a hash containing some of the
+information in the statfs structure.
+
+As with the return stack, it would be possible (and a small performance win)
+to pre-extend the return array before pushing data into it, since we know
+how many elements we will return:
+
+ av_extend(results, numpaths);
+
+=item *
+
+We are performing only one hash operation in this function, which is storing
+a new scalar under a key using C<hv_store>. A hash is represented by an HV*
+pointer. Like arrays, the functions for manipulating hashes from an XSUB
+mirror the functionality available from Perl. See L<perlguts> and L<perlapi>
+for details.
+
+=item *
+
+To create a reference, we use the C<newRV_inc> function. Note that you can
+cast an AV* or an HV* to type SV* in this case (and many others). This
+allows you to take references to arrays, hashes and scalars with the same
+function. Conversely, the C<SvRV> function always returns an SV*, which may
+need to be cast to the appropriate type if it is something other than a
+scalar (check with C<SvTYPE>).
+
+=item *
+
+At this point, xsubpp is doing very little work - the differences between
+Mytest.xs and Mytest.c are minimal.
+
+=back
+
+=head2 EXAMPLE 7 (Coming Soon)
+
+XPUSH args AND set RETVAL AND assign return value to array
+
+=head2 EXAMPLE 8 (Coming Soon)
+
+Setting $!
+
+=head2 EXAMPLE 9 Passing open files to XSes
+
+You would think passing files to an XS is difficult, with all the
+typeglobs and stuff. Well, it isn't.
+
+Suppose that for some strange reason we need a wrapper around the
+standard C library function C<fputs()>. This is all we need:
+
+ #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */
+ #define PERL_NO_GET_CONTEXT /* This is more efficient */
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ #include <stdio.h>
+
+ int
+ fputs(s, stream)
+ char * s
+ FILE * stream
+
+The real work is done in the standard typemap.
+
+For more details, see
+L<perlapio/"Co-existence with stdio">.
+
+B<But> you lose all the fine stuff done by the perlio layers. This
+calls the stdio function C<fputs()>, which knows nothing about them.
+
+The standard typemap offers three variants of PerlIO *:
+C<InputStream> (T_IN), C<InOutStream> (T_INOUT) and C<OutputStream>
+(T_OUT). A bare C<PerlIO *> is considered a T_INOUT. If it matters
+in your code (see below for why it might) #define or typedef
+one of the specific names and use that as the argument or result
+type in your XS file.
+
+The standard typemap does not contain PerlIO * before perl 5.7,
+but it has the three stream variants. Using a PerlIO * directly
+is not backwards compatible unless you provide your own typemap.
+
+For streams coming I<from> perl the main difference is that
+C<OutputStream> will get the output PerlIO * - which may make
+a difference on a socket. Like in our example...
+
+For streams being handed I<to> perl a new file handle is created
+(i.e. a reference to a new glob) and associated with the PerlIO *
+provided. If the read/write state of the PerlIO * is not correct then you
+may get errors or warnings from when the file handle is used.
+So if you opened the PerlIO * as "w" it should really be an
+C<OutputStream> if open as "r" it should be an C<InputStream>.
+
+Now, suppose you want to use perlio layers in your XS. We'll use the
+perlio C<PerlIO_puts()> function as an example.
+
+In the C part of the XS file (above the first MODULE line) you
+have
+
+ #define OutputStream PerlIO *
+ or
+ typedef PerlIO * OutputStream;
+
+
+And this is the XS code:
+
+ int
+ perlioputs(s, stream)
+ char * s
+ OutputStream stream
+ CODE:
+ RETVAL = PerlIO_puts(stream, s);
+ OUTPUT:
+ RETVAL
+
+We have to use a C<CODE> section because C<PerlIO_puts()> has the arguments
+reversed compared to C<fputs()>, and we want to keep the arguments the same.
+
+Wanting to explore this thoroughly, we want to use the stdio C<fputs()>
+on a PerlIO *. This means we have to ask the perlio system for a stdio
+C<FILE *>:
+
+ int
+ perliofputs(s, stream)
+ char * s
+ OutputStream stream
+ PREINIT:
+ FILE *fp = PerlIO_findFILE(stream);
+ CODE:
+ if (fp != (FILE*) 0) {
+ RETVAL = fputs(s, fp);
+ } else {
+ RETVAL = -1;
+ }
+ OUTPUT:
+ RETVAL
+
+Note: C<PerlIO_findFILE()> will search the layers for a stdio
+layer. If it can't find one, it will call C<PerlIO_exportFILE()> to
+generate a new stdio C<FILE>. Please only call C<PerlIO_exportFILE()> if
+you want a I<new> C<FILE>. It will generate one on each call and push a
+new stdio layer. So don't call it repeatedly on the same
+file. C<PerlIO_findFILE()> will retrieve the stdio layer once it has been
+generated by C<PerlIO_exportFILE()>.
+
+This applies to the perlio system only. For versions before 5.7,
+C<PerlIO_exportFILE()> is equivalent to C<PerlIO_findFILE()>.
+
+=head2 Troubleshooting these Examples
+
+As mentioned at the top of this document, if you are having problems with
+these example extensions, you might see if any of these help you.
+
+=over 4
+
+=item *
+
+In versions of 5.002 prior to the gamma version, the test script in Example
+1 will not function properly. You need to change the "use lib" line to
+read:
+
+ use lib './blib';
+
+=item *
+
+In versions of 5.002 prior to version 5.002b1h, the test.pl file was not
+automatically created by h2xs. This means that you cannot say "make test"
+to run the test script. You will need to add the following line before the
+"use extension" statement:
+
+ use lib './blib';
+
+=item *
+
+In versions 5.000 and 5.001, instead of using the above line, you will need
+to use the following line:
+
+ BEGIN { unshift(@INC, "./blib") }
+
+=item *
+
+This document assumes that the executable named "perl" is Perl version 5.
+Some systems may have installed Perl version 5 as "perl5".
+
+=back
+
+=head1 See also
+
+For more information, consult L<perlguts>, L<perlapi>, L<perlxs>, L<perlmod>,
+L<perlapio>, and L<perlpod>
+
+=head1 Author
+
+Jeff Okamoto <F<okamoto@corp.hp.com>>
+
+Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
+and Tim Bunce.
+
+PerlIO material contributed by Lupe Christoph, with some clarification
+by Nick Ing-Simmons.
+
+Changes for h2xs as of Perl 5.8.x by Renee Baecker
+
+This document is now maintained as part of Perl itself.
+
+=head2 Last Changed
+
+2020-10-05
diff --git a/lib/perlxstypemap.pod b/lib/perlxstypemap.pod
new file mode 100644
index 0000000..7d1f73c
--- /dev/null
+++ b/lib/perlxstypemap.pod
@@ -0,0 +1,711 @@
+=head1 NAME
+
+perlxstypemap - Perl XS C/Perl type mapping
+
+=head1 DESCRIPTION
+
+The more you think about interfacing between two languages, the more
+you'll realize that the majority of programmer effort has to go into
+converting between the data structures that are native to either of
+the languages involved. This trumps other matter such as differing
+calling conventions because the problem space is so much greater.
+There are simply more ways to shove data into memory than there are
+ways to implement a function call.
+
+Perl XS' attempt at a solution to this is the concept of typemaps.
+At an abstract level, a Perl XS typemap is nothing but a recipe for
+converting from a certain Perl data structure to a certain C
+data structure and vice versa. Since there can be C types that
+are sufficiently similar to one another to warrant converting with
+the same logic, XS typemaps are represented by a unique identifier,
+henceforth called an B<XS type> in this document. You can then tell
+the XS compiler that multiple C types are to be mapped with the same
+XS typemap.
+
+In your XS code, when you define an argument with a C type or when
+you are using a C<CODE:> and an C<OUTPUT:> section together with a
+C return type of your XSUB, it'll be the typemapping mechanism that
+makes this easy.
+
+=head2 Anatomy of a typemap
+
+In more practical terms, the typemap is a collection of code
+fragments which are used by the B<xsubpp> compiler to map C function
+parameters and values to Perl values. The typemap file may consist
+of three sections labelled C<TYPEMAP>, C<INPUT>, and C<OUTPUT>.
+An unlabelled initial section is assumed to be a C<TYPEMAP> section.
+The INPUT section tells the compiler how to translate Perl values
+into variables of certain C types. The OUTPUT section tells the
+compiler how to translate the values from certain C types into values
+Perl can understand. The TYPEMAP section tells the compiler which
+of the INPUT and OUTPUT code fragments should be used to map a given
+C type to a Perl value. The section labels C<TYPEMAP>, C<INPUT>, or
+C<OUTPUT> must begin in the first column on a line by themselves,
+and must be in uppercase.
+
+Each type of section can appear an arbitrary number of times
+and does not have to appear at all. For example, a typemap may
+commonly lack C<INPUT> and C<OUTPUT> sections if all it needs to
+do is associate additional C types with core XS types like T_PTROBJ.
+Lines that start with a hash C<#> are considered comments and ignored
+in the C<TYPEMAP> section, but are considered significant in C<INPUT>
+and C<OUTPUT>. Blank lines are generally ignored.
+
+Traditionally, typemaps needed to be written to a separate file,
+conventionally called C<typemap> in a CPAN distribution. With
+ExtUtils::ParseXS (the XS compiler) version 3.12 or better which
+comes with perl 5.16, typemaps can also be embedded directly into
+XS code using a HERE-doc like syntax:
+
+ TYPEMAP: <<HERE
+ ...
+ HERE
+
+where C<HERE> can be replaced by other identifiers like with normal
+Perl HERE-docs. All details below about the typemap textual format
+remain valid.
+
+The C<TYPEMAP> section should contain one pair of C type and
+XS type per line as follows. An example from the core typemap file:
+
+ TYPEMAP
+ # all variants of char* is handled by the T_PV typemap
+ char * T_PV
+ const char * T_PV
+ unsigned char * T_PV
+ ...
+
+The C<INPUT> and C<OUTPUT> sections have identical formats, that is,
+each unindented line starts a new in- or output map respectively.
+A new in- or output map must start with the name of the XS type to
+map on a line by itself, followed by the code that implements it
+indented on the following lines. Example:
+
+ INPUT
+ T_PV
+ $var = ($type)SvPV_nolen($arg)
+ T_PTR
+ $var = INT2PTR($type,SvIV($arg))
+
+We'll get to the meaning of those Perlish-looking variables in a
+little bit.
+
+Finally, here's an example of the full typemap file for mapping C
+strings of the C<char *> type to Perl scalars/strings:
+
+ TYPEMAP
+ char * T_PV
+
+ INPUT
+ T_PV
+ $var = ($type)SvPV_nolen($arg)
+
+ OUTPUT
+ T_PV
+ sv_setpv((SV*)$arg, $var);
+
+Here's a more complicated example: suppose that you wanted
+C<struct netconfig> to be blessed into the class C<Net::Config>.
+One way to do this is to use underscores (_) to separate package
+names, as follows:
+
+ typedef struct netconfig * Net_Config;
+
+And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps
+underscores to double-colons (::), and declare C<Net_Config> to be of
+that type:
+
+ TYPEMAP
+ Net_Config T_PTROBJ_SPECIAL
+
+ INPUT
+ T_PTROBJ_SPECIAL
+ if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")){
+ IV tmp = SvIV((SV*)SvRV($arg));
+ $var = INT2PTR($type, tmp);
+ }
+ else
+ croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
+
+ OUTPUT
+ T_PTROBJ_SPECIAL
+ sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
+ (void*)$var);
+
+The INPUT and OUTPUT sections substitute underscores for double-colons
+on the fly, giving the desired effect. This example demonstrates some
+of the power and versatility of the typemap facility.
+
+The C<INT2PTR> macro (defined in perl.h) casts an integer to a pointer
+of a given type, taking care of the possible different size of integers
+and pointers. There are also C<PTR2IV>, C<PTR2UV>, C<PTR2NV> macros,
+to map the other way, which may be useful in OUTPUT sections.
+
+=head2 The Role of the typemap File in Your Distribution
+
+The default typemap in the F<lib/ExtUtils> directory of the Perl source
+contains many useful types which can be used by Perl extensions. Some
+extensions define additional typemaps which they keep in their own directory.
+These additional typemaps may reference INPUT and OUTPUT maps in the main
+typemap. The B<xsubpp> compiler will allow the extension's own typemap to
+override any mappings which are in the default typemap. Instead of using
+an additional F<typemap> file, typemaps may be embedded verbatim in XS
+with a heredoc-like syntax. See the documentation on the C<TYPEMAP:> XS
+keyword.
+
+For CPAN distributions, you can assume that the XS types defined by
+the perl core are already available. Additionally, the core typemap
+has default XS types for a large number of C types. For example, if
+you simply return a C<char *> from your XSUB, the core typemap will
+have this C type associated with the T_PV XS type. That means your
+C string will be copied into the PV (pointer value) slot of a new scalar
+that will be returned from your XSUB to Perl.
+
+If you're developing a CPAN distribution using XS, you may add your own
+file called F<typemap> to the distribution. That file may contain
+typemaps that either map types that are specific to your code or that
+override the core typemap file's mappings for common C types.
+
+=head2 Sharing typemaps Between CPAN Distributions
+
+Starting with ExtUtils::ParseXS version 3.13_01 (comes with perl 5.16
+and better), it is rather easy to share typemap code between multiple
+CPAN distributions. The general idea is to share it as a module that
+offers a certain API and have the dependent modules declare that as a
+built-time requirement and import the typemap into the XS. An example
+of such a typemap-sharing module on CPAN is
+C<ExtUtils::Typemaps::Basic>. Two steps to getting that module's
+typemaps available in your code:
+
+=over 4
+
+=item *
+
+Declare C<ExtUtils::Typemaps::Basic> as a build-time dependency
+in C<Makefile.PL> (use C<BUILD_REQUIRES>), or in your C<Build.PL>
+(use C<build_requires>).
+
+=item *
+
+Include the following line in the XS section of your XS file:
+(don't break the line)
+
+ INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd
+ -e "print embeddable_typemap(q{Basic})"
+
+=back
+
+=head2 Writing typemap Entries
+
+Each INPUT or OUTPUT typemap entry is a double-quoted Perl string that
+will be evaluated in the presence of certain variables to get the
+final C code for mapping a certain C type.
+
+This means that you can embed Perl code in your typemap (C) code using
+constructs such as
+C<${ perl code that evaluates to scalar reference here }>. A common
+use case is to generate error messages that refer to the true function
+name even when using the ALIAS XS feature:
+
+ ${ $ALIAS ? \q[GvNAME(CvGV(cv))] : \qq[\"$pname\"] }
+
+For many typemap examples, refer to the core typemap file that can be
+found in the perl source tree at F<lib/ExtUtils/typemap>.
+
+The Perl variables that are available for interpolation into typemaps
+are the following:
+
+=over 4
+
+=item *
+
+I<$var> - the name of the input or output variable, eg. RETVAL for
+return values.
+
+=item *
+
+I<$type> - the raw C type of the parameter, any C<:> replaced with
+C<_>.
+e.g. for a type of C<Foo::Bar>, I<$type> is C<Foo__Bar>
+
+=item *
+
+I<$ntype> - the supplied type with C<*> replaced with C<Ptr>.
+e.g. for a type of C<Foo*>, I<$ntype> is C<FooPtr>
+
+=item *
+
+I<$arg> - the stack entry, that the parameter is input from or output
+to, e.g. C<ST(0)>
+
+=item *
+
+I<$argoff> - the argument stack offset of the argument. ie. 0 for the
+first argument, etc.
+
+=item *
+
+I<$pname> - the full name of the XSUB, with including the C<PACKAGE>
+name, with any C<PREFIX> stripped. This is the non-ALIAS name.
+
+=item *
+
+I<$Package> - the package specified by the most recent C<PACKAGE>
+keyword.
+
+=item *
+
+I<$ALIAS> - non-zero if the current XSUB has any aliases declared with
+C<ALIAS>.
+
+=back
+
+=head2 Full Listing of Core Typemaps
+
+Each C type is represented by an entry in the typemap file that
+is responsible for converting perl variables (SV, AV, HV, CV, etc.)
+to and from that type. The following sections list all XS types
+that come with perl by default.
+
+=over 4
+
+=item T_SV
+
+This simply passes the C representation of the Perl variable (an SV*)
+in and out of the XS layer. This can be used if the C code wants
+to deal directly with the Perl variable.
+
+=item T_SVREF
+
+Used to pass in and return a reference to an SV.
+
+Note that this typemap does not decrement the reference count
+when returning the reference to an SV*.
+See also: T_SVREF_REFCOUNT_FIXED
+
+=item T_SVREF_FIXED
+
+Used to pass in and return a reference to an SV.
+This is a fixed
+variant of T_SVREF that decrements the refcount appropriately
+when returning a reference to an SV*. Introduced in perl 5.15.4.
+
+=item T_AVREF
+
+From the perl level this is a reference to a perl array.
+From the C level this is a pointer to an AV.
+
+Note that this typemap does not decrement the reference count
+when returning an AV*. See also: T_AVREF_REFCOUNT_FIXED
+
+=item T_AVREF_REFCOUNT_FIXED
+
+From the perl level this is a reference to a perl array.
+From the C level this is a pointer to an AV. This is a fixed
+variant of T_AVREF that decrements the refcount appropriately
+when returning an AV*. Introduced in perl 5.15.4.
+
+=item T_HVREF
+
+From the perl level this is a reference to a perl hash.
+From the C level this is a pointer to an HV.
+
+Note that this typemap does not decrement the reference count
+when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
+
+=item T_HVREF_REFCOUNT_FIXED
+
+From the perl level this is a reference to a perl hash.
+From the C level this is a pointer to an HV. This is a fixed
+variant of T_HVREF that decrements the refcount appropriately
+when returning an HV*. Introduced in perl 5.15.4.
+
+=item T_CVREF
+
+From the perl level this is a reference to a perl subroutine
+(e.g. $sub = sub { 1 };). From the C level this is a pointer
+to a CV.
+
+Note that this typemap does not decrement the reference count
+when returning an HV*. See also: T_HVREF_REFCOUNT_FIXED
+
+=item T_CVREF_REFCOUNT_FIXED
+
+From the perl level this is a reference to a perl subroutine
+(e.g. $sub = sub { 1 };). From the C level this is a pointer
+to a CV.
+
+This is a fixed
+variant of T_HVREF that decrements the refcount appropriately
+when returning an HV*. Introduced in perl 5.15.4.
+
+=item T_SYSRET
+
+The T_SYSRET typemap is used to process return values from system calls.
+It is only meaningful when passing values from C to perl (there is
+no concept of passing a system return value from Perl to C).
+
+System calls return -1 on error (setting ERRNO with the reason)
+and (usually) 0 on success. If the return value is -1 this typemap
+returns C<undef>. If the return value is not -1, this typemap
+translates a 0 (perl false) to "0 but true" (which
+is perl true) or returns the value itself, to indicate that the
+command succeeded.
+
+The L<POSIX|POSIX> module makes extensive use of this type.
+
+=item T_UV
+
+An unsigned integer.
+
+=item T_IV
+
+A signed integer. This is cast to the required integer type when
+passed to C and converted to an IV when passed back to Perl.
+
+=item T_INT
+
+A signed integer. This typemap converts the Perl value to a native
+integer type (the C<int> type on the current platform). When returning
+the value to perl it is processed in the same way as for T_IV.
+
+Its behaviour is identical to using an C<int> type in XS with T_IV.
+
+=item T_ENUM
+
+An enum value. Used to transfer an enum component
+from C. There is no reason to pass an enum value to C since
+it is stored as an IV inside perl.
+
+=item T_BOOL
+
+A boolean type. This can be used to pass true and false values to and
+from C.
+
+=item T_U_INT
+
+This is for unsigned integers. It is equivalent to using T_UV
+but explicitly casts the variable to type C<unsigned int>.
+The default type for C<unsigned int> is T_UV.
+
+=item T_SHORT
+
+Short integers. This is equivalent to T_IV but explicitly casts
+the return to type C<short>. The default typemap for C<short>
+is T_IV.
+
+=item T_U_SHORT
+
+Unsigned short integers. This is equivalent to T_UV but explicitly
+casts the return to type C<unsigned short>. The default typemap for
+C<unsigned short> is T_UV.
+
+T_U_SHORT is used for type C<U16> in the standard typemap.
+
+=item T_LONG
+
+Long integers. This is equivalent to T_IV but explicitly casts
+the return to type C<long>. The default typemap for C<long>
+is T_IV.
+
+=item T_U_LONG
+
+Unsigned long integers. This is equivalent to T_UV but explicitly
+casts the return to type C<unsigned long>. The default typemap for
+C<unsigned long> is T_UV.
+
+T_U_LONG is used for type C<U32> in the standard typemap.
+
+=item T_CHAR
+
+Single 8-bit characters.
+
+=item T_U_CHAR
+
+An unsigned byte.
+
+=item T_FLOAT
+
+A floating point number. This typemap guarantees to return a variable
+cast to a C<float>.
+
+=item T_NV
+
+A Perl floating point number. Similar to T_IV and T_UV in that the
+return type is cast to the requested numeric type rather than
+to a specific type.
+
+=item T_DOUBLE
+
+A double precision floating point number. This typemap guarantees to
+return a variable cast to a C<double>.
+
+=item T_PV
+
+A string (char *).
+
+=item T_PTR
+
+A memory address (pointer). Typically associated with a C<void *>
+type.
+
+=item T_PTRREF
+
+Similar to T_PTR except that the pointer is stored in a scalar and the
+reference to that scalar is returned to the caller. This can be used
+to hide the actual pointer value from the programmer since it is usually
+not required directly from within perl.
+
+The typemap checks that a scalar reference is passed from perl to XS.
+
+=item T_PTROBJ
+
+Similar to T_PTRREF except that the reference is blessed into a class.
+This allows the pointer to be used as an object. Most commonly used to
+deal with C structs. The typemap checks that the perl object passed
+into the XS routine is of the correct class (or part of a subclass).
+
+The pointer is blessed into a class that is derived from the name
+of type of the pointer but with all '*' in the name replaced with
+'Ptr'.
+
+For C<DESTROY> XSUBs only, a T_PTROBJ is optimized to a T_PTRREF. This means
+the class check is skipped.
+
+=item T_REF_IV_REF
+
+NOT YET
+
+=item T_REF_IV_PTR
+
+Similar to T_PTROBJ in that the pointer is blessed into a scalar object.
+The difference is that when the object is passed back into XS it must be
+of the correct type (inheritance is not supported) while T_PTROBJ supports
+inheritance.
+
+The pointer is blessed into a class that is derived from the name
+of type of the pointer but with all '*' in the name replaced with
+'Ptr'.
+
+For C<DESTROY> XSUBs only, a T_REF_IV_PTR is optimized to a T_PTRREF. This
+means the class check is skipped.
+
+=item T_PTRDESC
+
+NOT YET
+
+=item T_REFREF
+
+Similar to T_PTRREF, except the pointer stored in the referenced scalar
+is dereferenced and copied to the output variable. This means that
+T_REFREF is to T_PTRREF as T_OPAQUE is to T_OPAQUEPTR. All clear?
+
+Only the INPUT part of this is implemented (Perl to XSUB) and there
+are no known users in core or on CPAN.
+
+=item T_REFOBJ
+
+Like T_REFREF, except it does strict type checking (inheritance is not
+supported).
+
+For C<DESTROY> XSUBs only, a T_REFOBJ is optimized to a T_REFREF. This means
+the class check is skipped.
+
+=item T_OPAQUEPTR
+
+This can be used to store bytes in the string component of the
+SV. Here the representation of the data is irrelevant to perl and the
+bytes themselves are just stored in the SV. It is assumed that the C
+variable is a pointer (the bytes are copied from that memory
+location). If the pointer is pointing to something that is
+represented by 8 bytes then those 8 bytes are stored in the SV (and
+length() will report a value of 8). This entry is similar to T_OPAQUE.
+
+In principle the unpack() command can be used to convert the bytes
+back to a number (if the underlying type is known to be a number).
+
+This entry can be used to store a C structure (the number
+of bytes to be copied is calculated using the C C<sizeof> function)
+and can be used as an alternative to T_PTRREF without having to worry
+about a memory leak (since Perl will clean up the SV).
+
+=item T_OPAQUE
+
+This can be used to store data from non-pointer types in the string
+part of an SV. It is similar to T_OPAQUEPTR except that the
+typemap retrieves the pointer directly rather than assuming it
+is being supplied. For example, if an integer is imported into
+Perl using T_OPAQUE rather than T_IV the underlying bytes representing
+the integer will be stored in the SV but the actual integer value will
+not be available. i.e. The data is opaque to perl.
+
+The data may be retrieved using the C<unpack> function if the
+underlying type of the byte stream is known.
+
+T_OPAQUE supports input and output of simple types.
+T_OPAQUEPTR can be used to pass these bytes back into C if a pointer
+is acceptable.
+
+=item Implicit array
+
+xsubpp supports a special syntax for returning
+packed C arrays to perl. If the XS return type is given as
+
+ array(type, nelem)
+
+xsubpp will copy the contents of C<nelem * sizeof(type)> bytes from
+RETVAL to an SV and push it onto the stack. This is only really useful
+if the number of items to be returned is known at compile time and you
+don't mind having a string of bytes in your SV. Use T_ARRAY to push a
+variable number of arguments onto the return stack (they won't be
+packed as a single string though).
+
+This is similar to using T_OPAQUEPTR but can be used to process more
+than one element.
+
+=item T_PACKED
+
+Calls user-supplied functions for conversion. For C<OUTPUT>
+(XSUB to Perl), a function named C<XS_pack_$ntype> is called
+with the output Perl scalar and the C variable to convert from.
+C<$ntype> is the normalized C type that is to be mapped to
+Perl. Normalized means that all C<*> are replaced by the
+string C<Ptr>. The return value of the function is ignored.
+
+Conversely for C<INPUT> (Perl to XSUB) mapping, the
+function named C<XS_unpack_$ntype> is called with the input Perl
+scalar as argument and the return value is cast to the mapped
+C type and assigned to the output C variable.
+
+An example conversion function for a typemapped struct
+C<foo_t *> might be:
+
+ static void
+ XS_pack_foo_tPtr(SV *out, foo_t *in)
+ {
+ dTHX; /* alas, signature does not include pTHX_ */
+ HV* hash = newHV();
+ hv_stores(hash, "int_member", newSViv(in->int_member));
+ hv_stores(hash, "float_member", newSVnv(in->float_member));
+ /* ... */
+
+ /* mortalize as thy stack is not refcounted */
+ sv_setsv(out, sv_2mortal(newRV_noinc((SV*)hash)));
+ }
+
+The conversion from Perl to C is left as an exercise to the reader,
+but the prototype would be:
+
+ static foo_t *
+ XS_unpack_foo_tPtr(SV *in);
+
+Instead of an actual C function that has to fetch the thread context
+using C<dTHX>, you can define macros of the same name and avoid the
+overhead. Also, keep in mind to possibly free the memory allocated by
+C<XS_unpack_foo_tPtr>.
+
+=item T_PACKEDARRAY
+
+T_PACKEDARRAY is similar to T_PACKED. In fact, the C<INPUT> (Perl
+to XSUB) typemap is identical, but the C<OUTPUT> typemap passes
+an additional argument to the C<XS_pack_$ntype> function. This
+third parameter indicates the number of elements in the output
+so that the function can handle C arrays sanely. The variable
+needs to be declared by the user and must have the name
+C<count_$ntype> where C<$ntype> is the normalized C type name
+as explained above. The signature of the function would be for
+the example above and C<foo_t **>:
+
+ static void
+ XS_pack_foo_tPtrPtr(SV *out, foo_t *in, UV count_foo_tPtrPtr);
+
+The type of the third parameter is arbitrary as far as the typemap
+is concerned. It just has to be in line with the declared variable.
+
+Of course, unless you know the number of elements in the
+C<sometype **> C array, within your XSUB, the return value from
+C<foo_t ** XS_unpack_foo_tPtrPtr(...)> will be hard to decipher.
+Since the details are all up to the XS author (the typemap user),
+there are several solutions, none of which particularly elegant.
+The most commonly seen solution has been to allocate memory for
+N+1 pointers and assign C<NULL> to the (N+1)th to facilitate
+iteration.
+
+Alternatively, using a customized typemap for your purposes in
+the first place is probably preferable.
+
+=item T_DATAUNIT
+
+NOT YET
+
+=item T_CALLBACK
+
+NOT YET
+
+=item T_ARRAY
+
+This is used to convert the perl argument list to a C array
+and for pushing the contents of a C array onto the perl
+argument stack.
+
+The usual calling signature is
+
+ @out = array_func( @in );
+
+Any number of arguments can occur in the list before the array but
+the input and output arrays must be the last elements in the list.
+
+When used to pass a perl list to C the XS writer must provide a
+function (named after the array type but with 'Ptr' substituted for
+'*') to allocate the memory required to hold the list. A pointer
+should be returned. It is up to the XS writer to free the memory on
+exit from the function. The variable C<ix_$var> is set to the number
+of elements in the new array.
+
+When returning a C array to Perl the XS writer must provide an integer
+variable called C<size_$var> containing the number of elements in the
+array. This is used to determine how many elements should be pushed
+onto the return argument stack. This is not required on input since
+Perl knows how many arguments are on the stack when the routine is
+called. Ordinarily this variable would be called C<size_RETVAL>.
+
+Additionally, the type of each element is determined from the type of
+the array. If the array uses type C<intArray *> xsubpp will
+automatically work out that it contains variables of type C<int> and
+use that typemap entry to perform the copy of each element. All
+pointer '*' and 'Array' tags are removed from the name to determine
+the subtype.
+
+=item T_STDIO
+
+This is used for passing perl filehandles to and from C using
+C<FILE *> structures.
+
+=item T_INOUT
+
+This is used for passing perl filehandles to and from C using
+C<PerlIO *> structures. The file handle can used for reading and
+writing. This corresponds to the C<+E<lt>> mode, see also T_IN
+and T_OUT.
+
+See L<perliol> for more information on the Perl IO abstraction
+layer. Perl must have been built with C<-Duseperlio>.
+
+There is no check to assert that the filehandle passed from Perl
+to C was created with the right C<open()> mode.
+
+Hint: The L<perlxstut> tutorial covers the T_INOUT, T_IN, and T_OUT
+XS types nicely.
+
+=item T_IN
+
+Same as T_INOUT, but the filehandle that is returned from C to Perl
+can only be used for reading (mode C<E<lt>>).
+
+=item T_OUT
+
+Same as T_INOUT, but the filehandle that is returned from C to Perl
+is set to use the open mode C<+E<gt>>.
+
+=back
+
diff --git a/t/001-basic.t b/t/001-basic.t
old mode 100755
new mode 100644
index 6651809..630da79
--- a/t/001-basic.t
+++ b/t/001-basic.t
@@ -1,7 +1,7 @@
#!/usr/bin/perl
use strict;
-use Test::More tests => 18;
+use Test::More tests => 30;
use Config;
use DynaLoader;
use ExtUtils::CBuilder;
@@ -15,7 +15,10 @@ require_ok( 'ExtUtils::ParseXS' );
chdir('t') if -d 't';
push @INC, '.';
-use Carp; $SIG{__WARN__} = \&Carp::cluck;
+$ExtUtils::ParseXS::DIE_ON_ERROR = 1;
+$ExtUtils::ParseXS::AUTHOR_WARNINGS = 1;
+
+use Carp; #$SIG{__WARN__} = \&Carp::cluck;
# The linker on some platforms doesn't like loading libraries using relative
# paths. Android won't find relative paths, and system perl on macOS will
@@ -91,6 +94,7 @@ is( $seen, 1, "Line numbers created in output file, as intended" );
local $/ = undef;
seek($IN, 0, 0);
my $filecontents = <$IN>;
+ $filecontents =~ s/^#if defined\(__HP_cc\).*\n#.*\n#endif\n//gm;
my $good_T_BOOL_re =
qr|\QXS_EUPXS(XS_XSTest_T_BOOL)\E
.+?
@@ -190,6 +194,182 @@ like $stderr, '/No INPUT definition/', "Exercise typemap error";
}
#####################################################################
+{ # fourth block: https://github.com/Perl/perl5/issues/19661
+ my $pxs = ExtUtils::ParseXS->new;
+ tie *FH, 'Foo';
+ my ($stderr, $filename);
+ {
+ $filename = 'XSFalsePositive.xs';
+ $stderr = PrimitiveCapture::capture_stderr(sub {
+ $pxs->process_file(filename => $filename, output => \*FH, prototypes => 1);
+ });
+ TODO: {
+ local $TODO = 'GH 19661';
+ unlike $stderr,
+ qr/Warning: duplicate function definition 'do' detected in \Q$filename\E/,
+ "No 'duplicate function definition' warning observed in $filename";
+ }
+ }
+ {
+ $filename = 'XSFalsePositive2.xs';
+ $stderr = PrimitiveCapture::capture_stderr(sub {
+ $pxs->process_file(filename => $filename, output => \*FH, prototypes => 1);
+ });
+ TODO: {
+ local $TODO = 'GH 19661';
+ unlike $stderr,
+ qr/Warning: duplicate function definition 'do' detected in \Q$filename\E/,
+ "No 'duplicate function definition' warning observed in $filename";
+ }
+ }
+}
+
+#####################################################################
+
+{ # tight cpp directives
+ my $pxs = ExtUtils::ParseXS->new;
+ tie *FH, 'Foo';
+ my $stderr = PrimitiveCapture::capture_stderr(sub { eval {
+ $pxs->process_file(
+ filename => 'XSTightDirectives.xs',
+ output => \*FH,
+ prototypes => 1);
+ } or warn $@ });
+ my $content = tied(*FH)->{buf};
+ my $count = 0;
+ $count++ while $content=~/^XS_EUPXS\(XS_My_do\)\n\{/mg;
+ is $stderr, undef, "No error expected from TightDirectives.xs";
+ is $count, 2, "Saw XS_MY_do definition the expected number of times";
+}
+
+{ # Alias check
+ my $pxs = ExtUtils::ParseXS->new;
+ tie *FH, 'Foo';
+ my $stderr = PrimitiveCapture::capture_stderr(sub {
+ $pxs->process_file(
+ filename => 'XSAlias.xs',
+ output => \*FH,
+ prototypes => 1);
+ });
+ my $content = tied(*FH)->{buf};
+ my $count = 0;
+ $count++ while $content=~/^XS_EUPXS\(XS_My_do\)\n\{/mg;
+ is $stderr,
+ "Warning: Aliases 'pox' and 'dox', 'lox' have"
+ . " identical values of 1 in XSAlias.xs, line 9\n"
+ . " (If this is deliberate use a symbolic alias instead.)\n"
+ . "Warning: Conflicting duplicate alias 'pox' changes"
+ . " definition from '1' to '2' in XSAlias.xs, line 10\n"
+ . "Warning: Aliases 'docks' and 'dox', 'lox' have"
+ . " identical values of 1 in XSAlias.xs, line 11\n"
+ . "Warning: Aliases 'xunx' and 'do' have identical values"
+ . " of 0 - the base function in XSAlias.xs, line 13\n",
+ "Saw expected warnings from XSAlias.xs in AUTHOR_WARNINGS mode";
+
+ my $expect = quotemeta(<<'EOF_CONTENT');
+ cv = newXSproto_portable("My::dachs", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::do", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+ cv = newXSproto_portable("My::docks", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::dox", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::lox", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::pox", XS_My_do, file, "$");
+ XSANY.any_i32 = 2;
+ cv = newXSproto_portable("My::xukes", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+ cv = newXSproto_portable("My::xunx", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+EOF_CONTENT
+ $expect=~s/(?:\\[ ])+/\\s+/g;
+ $expect=qr/$expect/;
+ like $content, $expect, "Saw expected alias initialization";
+
+ #diag $content;
+}
+{ # Alias check with no dev warnings.
+ my $pxs = ExtUtils::ParseXS->new;
+ tie *FH, 'Foo';
+ my $stderr = PrimitiveCapture::capture_stderr(sub {
+ $pxs->process_file(
+ filename => 'XSAlias.xs',
+ output => \*FH,
+ prototypes => 1,
+ author_warnings => 0);
+ });
+ my $content = tied(*FH)->{buf};
+ my $count = 0;
+ $count++ while $content=~/^XS_EUPXS\(XS_My_do\)\n\{/mg;
+ is $stderr,
+ "Warning: Conflicting duplicate alias 'pox' changes"
+ . " definition from '1' to '2' in XSAlias.xs, line 10\n",
+ "Saw expected warnings from XSAlias.xs";
+
+ my $expect = quotemeta(<<'EOF_CONTENT');
+ cv = newXSproto_portable("My::dachs", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::do", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+ cv = newXSproto_portable("My::docks", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::dox", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::lox", XS_My_do, file, "$");
+ XSANY.any_i32 = 1;
+ cv = newXSproto_portable("My::pox", XS_My_do, file, "$");
+ XSANY.any_i32 = 2;
+ cv = newXSproto_portable("My::xukes", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+ cv = newXSproto_portable("My::xunx", XS_My_do, file, "$");
+ XSANY.any_i32 = 0;
+EOF_CONTENT
+ $expect=~s/(?:\\[ ])+/\\s+/g;
+ $expect=qr/$expect/;
+ like $content, $expect, "Saw expected alias initialization";
+
+ #diag $content;
+}
+{
+ my $file = $INC{"ExtUtils/ParseXS.pm"};
+ $file=~s!ExtUtils/ParseXS\.pm\z!perlxs.pod!;
+ open my $fh, "<", $file
+ or die "Failed to open '$file' for read:$!";
+ my $pod_version = "";
+ while (defined(my $line= readline($fh))) {
+ if ($line=~/\(also known as C<xsubpp>\)\s+(\d+\.\d+)/) {
+ $pod_version = $1;
+ last;
+ }
+ }
+ close $fh;
+ ok($pod_version, "Found the version from perlxs.pod");
+ is($pod_version, $ExtUtils::ParseXS::VERSION,
+ "The version in perlxs.pod should match the version of ExtUtils::ParseXS");
+}
+
+{
+ my $pxs = ExtUtils::ParseXS->new;
+ tie *FH, 'Foo';
+ my $exception;
+ my $stderr = PrimitiveCapture::capture_stderr(sub {
+ eval {
+ $pxs->process_file(
+ filename => "XSNoMap.xs",
+ output => \*FH,
+ );
+ 1;
+ } or $exception = $@;
+ });
+ is($stderr, undef, "should fail to parse");
+ like($exception, qr/Could not find a typemap for C type 'S \*'/,
+ "check we throw rather than trying to deref '2'");
+}
+
+#####################################################################
+
sub Foo::TIEHANDLE { bless {}, 'Foo' }
sub Foo::PRINT { shift->{buf} .= join '', @_ }
sub Foo::content { shift->{buf} }
diff --git a/t/002-more.t b/t/002-more.t
old mode 100755
new mode 100644
index 1ed93a0..f118f2c
--- a/t/002-more.t
+++ b/t/002-more.t
@@ -9,7 +9,7 @@ use ExtUtils::CBuilder;
use attributes;
use overload;
-plan tests => 32;
+plan tests => 33;
my ($source_file, $obj_file, $lib_file);
@@ -19,7 +19,7 @@ ExtUtils::ParseXS->import('process_file');
chdir 't' if -d 't';
push @INC, '.';
-use Carp; $SIG{__WARN__} = \&Carp::cluck;
+use Carp; #$SIG{__WARN__} = \&Carp::cluck;
# See the comments about this in 001-basics.t
@INC = map { File::Spec->rel2abs($_) } @INC;
@@ -47,7 +47,7 @@ SKIP: {
}
SKIP: {
- skip "no dynamic loading", 28
+ skip "no dynamic loading", 29
if !$b->have_compiler || !$Config{usedl};
my $module = 'XSMore';
$lib_file = $b->link( objects => $obj_file, module_name => $module );
@@ -85,6 +85,9 @@ SKIP: {
ok overload::Overloaded(XSMore->new), 'the FALLBACK keyword';
is abs(XSMore->new), 42, 'the OVERLOAD keyword';
+ my $overload_sub_name = "XSMore::More::(+";
+ is prototype(\&$overload_sub_name), "", 'OVERLOAD following prototyped xsub';
+
my @a;
XSMore::hook(\@a);
is_deeply \@a, [qw(INIT CODE POSTCALL CLEANUP)], 'the INIT & POSTCALL & CLEANUP keywords';
diff --git a/t/003-usage.t b/t/003-usage.t
old mode 100755
new mode 100644
index 52b9903..f33e3e0
--- a/t/003-usage.t
+++ b/t/003-usage.t
@@ -20,7 +20,7 @@ require_ok( 'ExtUtils::ParseXS' );
chdir('t') if -d 't';
push @INC, '.';
-use Carp; $SIG{__WARN__} = \&Carp::cluck;
+use Carp; #$SIG{__WARN__} = \&Carp::cluck;
# See the comments about this in 001-basics.t
@INC = map { File::Spec->rel2abs($_) } @INC;
diff --git a/t/101-standard_typemap_locations.t b/t/101-standard_typemap_locations.t
old mode 100755
new mode 100644
diff --git a/t/102-trim_whitespace.t b/t/102-trim_whitespace.t
old mode 100755
new mode 100644
diff --git a/t/103-tidy_type.t b/t/103-tidy_type.t
old mode 100755
new mode 100644
diff --git a/t/104-map_type.t b/t/104-map_type.t
old mode 100755
new mode 100644
diff --git a/t/105-valid_proto_string.t b/t/105-valid_proto_string.t
old mode 100755
new mode 100644
diff --git a/t/106-process_typemaps.t b/t/106-process_typemaps.t
old mode 100755
new mode 100644
diff --git a/t/108-map_type.t b/t/108-map_type.t
old mode 100755
new mode 100644
diff --git a/t/109-standard_XS_defs.t b/t/109-standard_XS_defs.t
old mode 100755
new mode 100644
diff --git a/t/110-assign_func_args.t b/t/110-assign_func_args.t
old mode 100755
new mode 100644
diff --git a/t/111-analyze_preprocessor_statements.t b/t/111-analyze_preprocessor_statements.t
old mode 100755
new mode 100644
diff --git a/t/112-set_cond.t b/t/112-set_cond.t
old mode 100755
new mode 100644
diff --git a/t/113-check_cond_preproc_statements.t b/t/113-check_cond_preproc_statements.t
old mode 100755
new mode 100644
diff --git a/t/114-blurt_death_Warn.t b/t/114-blurt_death_Warn.t
old mode 100755
new mode 100644
diff --git a/t/115-avoid-noise.t b/t/115-avoid-noise.t
old mode 100755
new mode 100644
diff --git a/t/501-t-compile.t b/t/501-t-compile.t
old mode 100755
new mode 100644
diff --git a/t/510-t-bare.t b/t/510-t-bare.t
old mode 100755
new mode 100644
diff --git a/t/511-t-whitespace.t b/t/511-t-whitespace.t
old mode 100755
new mode 100644
diff --git a/t/512-t-file.t b/t/512-t-file.t
old mode 100755
new mode 100644
diff --git a/t/513-t-merge.t b/t/513-t-merge.t
old mode 100755
new mode 100644
diff --git a/t/514-t-embed.t b/t/514-t-embed.t
old mode 100755
new mode 100644
diff --git a/t/515-t-cmd.t b/t/515-t-cmd.t
old mode 100755
new mode 100644
diff --git a/t/516-t-clone.t b/t/516-t-clone.t
old mode 100755
new mode 100644
diff --git a/t/517-t-targetable.t b/t/517-t-targetable.t
old mode 100755
new mode 100644
diff --git a/t/600-t-compat.t b/t/600-t-compat.t
old mode 100755
new mode 100644
diff --git a/t/XSAlias.xs b/t/XSAlias.xs
new file mode 100644
index 0000000..fcd98e2
--- /dev/null
+++ b/t/XSAlias.xs
@@ -0,0 +1,19 @@
+MODULE = My PACKAGE = My
+
+void
+do(dbh)
+ SV *dbh
+ALIAS:
+ dox = 1
+ lox => dox
+ pox = 1
+ pox = 2
+ docks = 1
+ dachs => lox
+ xunx = 0
+ xukes => do
+CODE:
+{
+ int x;
+ ++x;
+}
diff --git a/t/XSFalsePositive.xs b/t/XSFalsePositive.xs
new file mode 100644
index 0000000..87a9330
--- /dev/null
+++ b/t/XSFalsePositive.xs
@@ -0,0 +1,23 @@
+MODULE = My PACKAGE = My
+
+#ifdef MYDEF123
+
+void
+do(dbh)
+ SV *dbh
+CODE:
+{
+ int x;
+ ++x;
+}
+
+#endif
+
+void
+do(dbh)
+ SV *dbh
+CODE:
+{
+ int x;
+ ++x;
+}
diff --git a/t/XSFalsePositive2.xs b/t/XSFalsePositive2.xs
new file mode 100644
index 0000000..4e0ca7e
--- /dev/null
+++ b/t/XSFalsePositive2.xs
@@ -0,0 +1,23 @@
+MODULE = My PACKAGE = My
+
+#ifdef MYDEF123
+
+void
+do(xdbh)
+ SV *xdbh
+CODE:
+{
+ int x;
+ ++x;
+}
+
+#endif
+
+void
+do(dbh)
+ SV *dbh
+CODE:
+{
+ int x;
+ ++x;
+}
diff --git a/t/XSMore.xs b/t/XSMore.xs
index f8413f4..b48cfa2 100644
--- a/t/XSMore.xs
+++ b/t/XSMore.xs
@@ -30,6 +30,10 @@ This parts are ignored.
# define PERL_UNUSED_VAR(x) ((void)x)
#endif
+/* Newx was introduced in 5.8.8, would also be in ppport.h */
+#ifndef Newx
+# define Newx(v,n,t) New(0,v,n,t)
+#endif
STATIC void
@@ -251,3 +255,17 @@ INCLUDE: XSInclude.xsh
# for testing #else directive
#endif
+
+MODULE=XSMore PACKAGE=XSMore::More
+
+void
+dummy()
+PROTOTYPE: $$$$$
+CODE:
+ NOOP;
+
+void
+should_not_have_prototype()
+OVERLOAD: +
+CODE:
+ NOOP;
diff --git a/t/XSNoMap.xs b/t/XSNoMap.xs
new file mode 100644
index 0000000..3ec199f
--- /dev/null
+++ b/t/XSNoMap.xs
@@ -0,0 +1,16 @@
+#include "EXTERN.h"
+#include "perl.h"
+#include "XSUB.h"
+
+typedef struct { int a; } S;
+
+static void
+xsnomap_unknown(S* p) {
+}
+
+MODULE = XSNoMap PACKAGE = XSNoMap PREFIX = xsnomap_
+
+PROTOTYPES: DISABLE
+
+void
+xsnomap_unknown(S *arg)
diff --git a/t/XSTightDirectives.xs b/t/XSTightDirectives.xs
new file mode 100644
index 0000000..aa83f12
--- /dev/null
+++ b/t/XSTightDirectives.xs
@@ -0,0 +1,21 @@
+MODULE = My PACKAGE = My
+
+#ifdef MYDEF123
+void
+do(dbh)
+ SV *dbh
+CODE:
+{
+ int x;
+ ++x;
+}
+#else
+void
+do(dbh)
+ SV *dbh
+CODE:
+{
+ int x;
+ ++x;
+}
+#endif
--
2.40.1
Reference in New Issue View Git Blame Copy Permalink