1package XS::APItest; 2 3use 5.008; 4use strict; 5use warnings; 6use Carp; 7 8use base qw/ DynaLoader Exporter /; 9 10# Items to export into callers namespace by default. Note: do not export 11# names by default without a very good reason. Use EXPORT_OK instead. 12# Do not simply export all your public functions/methods/constants. 13 14# Export everything since these functions are only used by a test script 15our @EXPORT = qw( print_double print_int print_long 16 print_float print_long_double have_long_double print_flush 17 mpushp mpushn mpushi mpushu 18 mxpushp mxpushn mxpushi mxpushu 19 call_sv call_pv call_method eval_sv eval_pv require_pv 20 G_SCALAR G_ARRAY G_VOID G_DISCARD G_EVAL G_NOARGS 21 G_KEEPERR G_NODEBUG G_METHOD G_WANT 22 apitest_exception mycroak strtab 23 my_cxt_getint my_cxt_getsv my_cxt_setint my_cxt_setsv 24 sv_setsv_cow_hashkey_core sv_setsv_cow_hashkey_notcore 25 rmagical_cast rmagical_flags 26 DPeek utf16_to_utf8 utf16_to_utf8_reversed pmflag my_exit 27); 28 29our $VERSION = '0.17'; 30 31use vars '$WARNINGS_ON_BOOTSTRAP'; 32use vars map "\$${_}_called_PP", qw(BEGIN UNITCHECK CHECK INIT END); 33 34BEGIN { 35 # This is arguably a hack, but it disposes of the UNITCHECK block without 36 # needing to preprocess the source code 37 if ($] < 5.009) { 38 eval 'sub UNITCHECK (&) {}; 1' or die $@; 39 } 40} 41 42# Do these here to verify that XS code and Perl code get called at the same 43# times 44BEGIN { 45 $BEGIN_called_PP++; 46} 47UNITCHECK { 48 $UNITCHECK_called_PP++; 49}; 50{ 51 # Need $W false by default, as some tests run under -w, and under -w we 52 # can get warnings about "Too late to run CHECK" block (and INIT block) 53 no warnings 'void'; 54 CHECK { 55 $CHECK_called_PP++; 56 } 57 INIT { 58 $INIT_called_PP++; 59 } 60} 61END { 62 $END_called_PP++; 63} 64 65if ($WARNINGS_ON_BOOTSTRAP) { 66 bootstrap XS::APItest $VERSION; 67} else { 68 # More CHECK and INIT blocks that could warn: 69 local $^W; 70 bootstrap XS::APItest $VERSION; 71} 72 731; 74__END__ 75 76=head1 NAME 77 78XS::APItest - Test the perl C API 79 80=head1 SYNOPSIS 81 82 use XS::APItest; 83 print_double(4); 84 85=head1 ABSTRACT 86 87This module tests the perl C API. Currently tests that C<printf> 88works correctly. 89 90=head1 DESCRIPTION 91 92This module can be used to check that the perl C API is behaving 93correctly. This module provides test functions and an associated 94test script that verifies the output. 95 96This module is not meant to be installed. 97 98=head2 EXPORT 99 100Exports all the test functions: 101 102=over 4 103 104=item B<print_double> 105 106Test that a double-precision floating point number is formatted 107correctly by C<printf>. 108 109 print_double( $val ); 110 111Output is sent to STDOUT. 112 113=item B<print_long_double> 114 115Test that a C<long double> is formatted correctly by 116C<printf>. Takes no arguments - the test value is hard-wired 117into the function (as "7"). 118 119 print_long_double(); 120 121Output is sent to STDOUT. 122 123=item B<have_long_double> 124 125Determine whether a C<long double> is supported by Perl. This should 126be used to determine whether to test C<print_long_double>. 127 128 print_long_double() if have_long_double; 129 130=item B<print_nv> 131 132Test that an C<NV> is formatted correctly by 133C<printf>. 134 135 print_nv( $val ); 136 137Output is sent to STDOUT. 138 139=item B<print_iv> 140 141Test that an C<IV> is formatted correctly by 142C<printf>. 143 144 print_iv( $val ); 145 146Output is sent to STDOUT. 147 148=item B<print_uv> 149 150Test that an C<UV> is formatted correctly by 151C<printf>. 152 153 print_uv( $val ); 154 155Output is sent to STDOUT. 156 157=item B<print_int> 158 159Test that an C<int> is formatted correctly by 160C<printf>. 161 162 print_int( $val ); 163 164Output is sent to STDOUT. 165 166=item B<print_long> 167 168Test that an C<long> is formatted correctly by 169C<printf>. 170 171 print_long( $val ); 172 173Output is sent to STDOUT. 174 175=item B<print_float> 176 177Test that a single-precision floating point number is formatted 178correctly by C<printf>. 179 180 print_float( $val ); 181 182Output is sent to STDOUT. 183 184=item B<call_sv>, B<call_pv>, B<call_method> 185 186These exercise the C calls of the same names. Everything after the flags 187arg is passed as the the args to the called function. They return whatever 188the C function itself pushed onto the stack, plus the return value from 189the function; for example 190 191 call_sv( sub { @_, 'c' }, G_ARRAY, 'a', 'b'); # returns 'a', 'b', 'c', 3 192 call_sv( sub { @_ }, G_SCALAR, 'a', 'b'); # returns 'b', 1 193 194=item B<eval_sv> 195 196Evaluates the passed SV. Result handling is done the same as for 197C<call_sv()> etc. 198 199=item B<eval_pv> 200 201Exercises the C function of the same name in scalar context. Returns the 202same SV that the C function returns. 203 204=item B<require_pv> 205 206Exercises the C function of the same name. Returns nothing. 207 208=back 209 210=head1 SEE ALSO 211 212L<XS::Typemap>, L<perlapi>. 213 214=head1 AUTHORS 215 216Tim Jenness, E<lt>t.jenness@jach.hawaii.eduE<gt>, 217Christian Soeller, E<lt>csoelle@mph.auckland.ac.nzE<gt>, 218Hugo van der Sanden E<lt>hv@crypt.compulink.co.ukE<gt> 219 220=head1 COPYRIGHT AND LICENSE 221 222Copyright (C) 2002,2004 Tim Jenness, Christian Soeller, Hugo van der Sanden. 223All Rights Reserved. 224 225This library is free software; you can redistribute it and/or modify 226it under the same terms as Perl itself. 227 228=cut 229