NAME
Devel::PPPort - Perl/Pollution/Portability
SYNOPSIS
Devel::PPPort::WriteFile(); # defaults to ./ppport.h Devel::PPPort::WriteFile('someheader.h');
DESCRIPTION
Perl's API has changed over time, gaining new features, new functions, increasing its flexibility, and reducing the impact on the C namespace environment (reduced pollution). The header file written by this module, typically ppport.h, attempts to bring some of the newer Perl API features to older versions of Perl, so that you can worry less about keeping track of old releases, but users can still reap the benefit.
Devel::PPPort contains a single function, called WriteFile
. Its
only purpose is to write the ppport.h C header file. This file
contains a series of macros and, if explicitly requested, functions that
allow XS modules to be built using older versions of Perl. Currently,
Perl versions from 5.003 to 5.9.2 are supported.
This module is used by h2xs
to write the file ppport.h.
Why use ppport.h?
You should use ppport.h in modern code so that your code will work with the widest range of Perl interpreters possible, without significant additional work.
You should attempt older code to fully use ppport.h, because the reduced pollution of newer Perl versions is an important thing. It's so important that the old polluting ways of original Perl modules will not be supported very far into the future, and your module will almost certainly break! By adapting to it now, you'll gain compatibility and a sense of having done the electronic ecology some good.
How to use ppport.h
Don't direct the users of your module to download Devel::PPPort.
They are most probably no XS writers. Also, don't make ppport.h
optional. Rather, just take the most recent copy of ppport.h that
you can find (e.g. by generating it with the latest Devel::PPPort
release from CPAN), copy it into your project, adjust your project to
use it, and distribute the header along with your module.
Running ppport.h
But ppport.h is more than just a C header. It's also a Perl script that can check your source code. It will suggest hints and portability notes, and can even make suggestions on how to change your code. You can run it like any other Perl program:
perl ppport.h
It also has embedded documentation, so you can use
perldoc ppport.h
to find out more about how to use it.
FUNCTIONS
WriteFile
WriteFile
takes one optional argument. When called with one
argument, it expects to be passed a filename. When called with
no arguments, it defaults to the filename ppport.h.
The function returns a true value if the file was written successfully. Otherwise it returns a false value.
COMPATIBILITY
ppport.h supports Perl versions from 5.003 to 5.9.2 in threaded and non-threaded configurations.
Provided Perl compatibility API
The header file written by this module, typically ppport.h, provides access to the following elements of the Perl API that is not available in older Perl releases:
_aMY_CXT
_pMY_CXT
aMY_CXT
aMY_CXT_
aTHX
aTHX_
AvFILLp
boolSV
call_argv
call_method
call_pv
call_sv
CopFILE
CopFILE_set
CopFILEAV
CopFILEGV
CopFILEGV_set
CopFILESV
CopSTASH
CopSTASH_eq
CopSTASH_set
CopSTASHPV
CopSTASHPV_set
CopyD
dAX
DEFSV
dITEMS
dMY_CXT
dMY_CXT_SV
dNOOP
dTHR
dTHX
dTHXa
dTHXoa
dUNDERBAR
END_EXTERN_C
ERRSV
eval_pv
eval_sv
EXTERN_C
get_av
get_cv
get_hv
get_sv
grok_bin
grok_hex
grok_number
GROK_NUMERIC_RADIX
grok_numeric_radix
grok_oct
gv_stashpvn
IN_LOCALE
IN_LOCALE_COMPILETIME
IN_LOCALE_RUNTIME
IN_PERL_COMPILETIME
INT2PTR
IS_NUMBER_GREATER_THAN_UV_MAX
IS_NUMBER_IN_UV
IS_NUMBER_INFINITY
IS_NUMBER_NAN
IS_NUMBER_NEG
IS_NUMBER_NOT_INT
IVdf
IVSIZE
IVTYPE
memEQ
memNE
MoveD
mPUSHi
mPUSHn
mPUSHp
mPUSHu
mXPUSHi
mXPUSHn
mXPUSHp
mXPUSHu
MY_CXT
MY_CXT_CLONE
MY_CXT_INIT
newCONSTSUB
newRV_inc
newRV_noinc
newSVpvn
newSVuv
NOOP
NUM2PTR
NVef
NVff
NVgf
NVTYPE
PERL_BCDVERSION
PERL_GCC_BRACE_GROUPS_FORBIDDEN
PERL_INT_MAX
PERL_INT_MIN
PERL_LONG_MAX
PERL_LONG_MIN
PERL_MAGIC_arylen
PERL_MAGIC_backref
PERL_MAGIC_bm
PERL_MAGIC_collxfrm
PERL_MAGIC_dbfile
PERL_MAGIC_dbline
PERL_MAGIC_defelem
PERL_MAGIC_env
PERL_MAGIC_envelem
PERL_MAGIC_ext
PERL_MAGIC_fm
PERL_MAGIC_glob
PERL_MAGIC_isa
PERL_MAGIC_isaelem
PERL_MAGIC_mutex
PERL_MAGIC_nkeys
PERL_MAGIC_overload
PERL_MAGIC_overload_elem
PERL_MAGIC_overload_table
PERL_MAGIC_pos
PERL_MAGIC_qr
PERL_MAGIC_regdata
PERL_MAGIC_regdatum
PERL_MAGIC_regex_global
PERL_MAGIC_shared
PERL_MAGIC_shared_scalar
PERL_MAGIC_sig
PERL_MAGIC_sigelem
PERL_MAGIC_substr
PERL_MAGIC_sv
PERL_MAGIC_taint
PERL_MAGIC_tied
PERL_MAGIC_tiedelem
PERL_MAGIC_tiedscalar
PERL_MAGIC_utf8
PERL_MAGIC_uvar
PERL_MAGIC_uvar_elem
PERL_MAGIC_vec
PERL_MAGIC_vstring
PERL_QUAD_MAX
PERL_QUAD_MIN
PERL_REVISION
PERL_SCAN_ALLOW_UNDERSCORES
PERL_SCAN_DISALLOW_PREFIX
PERL_SCAN_GREATER_THAN_UV_MAX
PERL_SCAN_SILENT_ILLDIGIT
PERL_SHORT_MAX
PERL_SHORT_MIN
PERL_SUBVERSION
PERL_UCHAR_MAX
PERL_UCHAR_MIN
PERL_UINT_MAX
PERL_UINT_MIN
PERL_ULONG_MAX
PERL_ULONG_MIN
PERL_UNUSED_DECL
PERL_UQUAD_MAX
PERL_UQUAD_MIN
PERL_USHORT_MAX
PERL_USHORT_MIN
PERL_VERSION
PL_compiling
PL_copline
PL_curcop
PL_curstash
PL_DBsingle
PL_DBsub
PL_debstash
PL_defgv
PL_diehook
PL_dirty
PL_dowarn
PL_errgv
PL_hexdigit
PL_hints
PL_na
PL_no_modify
PL_perl_destruct_level
PL_perldb
PL_ppaddr
PL_rsfp
PL_rsfp_filters
PL_stack_base
PL_stack_sp
PL_stdingv
PL_Sv
PL_sv_arenaroot
PL_sv_no
PL_sv_undef
PL_sv_yes
PL_tainted
PL_tainting
pMY_CXT
pMY_CXT_
Poison
pTHX
pTHX_
PTR2IV
PTR2NV
PTR2ul
PTR2UV
PTRV
PUSHmortal
PUSHu
SAVE_DEFSV
START_EXTERN_C
START_MY_CXT
STMT_END
STMT_START
sv_2pv_nolen
sv_2pvbyte
sv_2uv
sv_catpv_mg
sv_catpvf_mg
sv_catpvf_mg_nocontext
sv_catpvn_mg
sv_catpvn_nomg
sv_catsv_mg
sv_catsv_nomg
sv_pvn
sv_pvn_force
sv_pvn_nomg
sv_setiv_mg
sv_setnv_mg
sv_setpv_mg
sv_setpvf_mg
sv_setpvf_mg_nocontext
sv_setpvn_mg
sv_setsv_mg
sv_setsv_nomg
sv_setuv
sv_setuv_mg
sv_usepvn_mg
sv_uv
sv_vcatpvf
sv_vcatpvf_mg
sv_vsetpvf
sv_vsetpvf_mg
SvGETMAGIC
SvIV_nomg
SvPV_force_nomg
SvPV_nolen
SvPV_nomg
SvPVbyte
SvUV
SvUV_nomg
SvUVX
SvUVx
SvUVXx
UNDERBAR
UVof
UVSIZE
UVTYPE
UVuf
UVXf
UVxf
vnewSVpvf
XPUSHmortal
XPUSHu
XSRETURN_UV
XST_mUV
ZeroD
Perl API not supported by ppport.h
There is still a big part of the API not supported by ppport.h. Either because it doesn't make sense to back-port that part of the API, or simply because it hasn't been implemented yet. Patches welcome!
Here's a list of the currently unsupported API, and also the version of Perl below which it is unsupported:
SvPVbyte_force find_rundefsvoffset vnormal
hv_assert hv_clear_placeholders hv_scalar scan_version sv_2iv_flags sv_2uv_flags
new_version save_set_svflags upg_version vcmp vnumify vstringify
SvIsCOW SvIsCOW_shared_hash
SvVOK doing_taint is_utf8_string_loc packlist save_bool savestack_grow_cnt scan_vstring sv_cat_decode sv_compile_2op sv_setpviv sv_setpviv_mg unpackstring
hv_iternext_flags hv_store_flags is_utf8_idcont nothreadhook
PerlIO_clearerr PerlIO_close PerlIO_eof PerlIO_error PerlIO_fileno PerlIO_fill PerlIO_flush PerlIO_get_base PerlIO_get_bufsiz PerlIO_get_cnt PerlIO_get_ptr PerlIO_read PerlIO_seek PerlIO_set_cnt PerlIO_set_ptrcnt PerlIO_setlinebuf PerlIO_stderr PerlIO_stdin PerlIO_stdout PerlIO_tell PerlIO_unread PerlIO_write SvLOCK SvSHARE SvUNLOCK atfork_lock atfork_unlock custom_op_desc custom_op_name deb debstack debstackptrs gv_fetchmeth_autoload ibcmp_utf8 my_fork my_socketpair pack_cat perl_destruct pv_uni_display regclass_swash save_shared_pvref savesharedpv sortsv sv_copypv sv_magicext sv_nolocking sv_nosharing sv_nounlocking sv_recode_to_utf8 sv_uni_display to_uni_fold to_uni_lower to_uni_title to_uni_upper to_utf8_case to_utf8_fold to_utf8_lower to_utf8_title to_utf8_upper unpack_str uvchr_to_utf8_flags uvuni_to_utf8_flags vdeb
calloc getcwd_sv init_tm malloc mfree mini_mktime my_atof2 my_strftime op_null realloc sv_2pv_flags sv_catpvn_flags sv_catsv_flags sv_pvn_force_flags sv_setsv_flags sv_utf8_upgrade_flags swash_fetch
POPpbytex SvUOK bytes_from_utf8 csighandler despatch_signals do_openn gv_handler is_lvalue_sub my_popen_list newSVpvn_share save_mortalizesv save_padsv scan_num sv_force_normal_flags sv_setref_uv sv_unref_flags sv_utf8_upgrade utf8_length utf8_to_uvchr utf8_to_uvuni utf8n_to_uvchr utf8n_to_uvuni uvchr_to_utf8 uvuni_to_utf8
apply_attrs_string bytes_to_utf8 gv_efullname4 gv_fullname4 is_utf8_string save_generic_pvref utf16_to_utf8 utf16_to_utf8_reversed utf8_to_bytes
SvIOK_UV SvIOK_notUV SvIOK_only_UV SvPOK_only_UTF8 SvPVbyte_nolen SvPVbytex SvPVbytex_force SvPVutf8 SvPVutf8_force SvPVutf8_nolen SvPVutf8x SvPVutf8x_force SvUTF8 SvUTF8_off SvUTF8_on av_delete av_exists call_atexit cast_i32 cast_iv cast_ulong cast_uv do_gv_dump do_gvgv_dump do_hv_dump do_magic_dump do_op_dump do_open9 do_pmop_dump do_sv_dump dump_all dump_eval dump_form dump_indent dump_packsubs dump_sub dump_vindent get_context get_ppaddr gv_dump init_i18nl10n init_i18nl14n is_uni_alnum is_uni_alnum_lc is_uni_alnumc is_uni_alnumc_lc is_uni_alpha is_uni_alpha_lc is_uni_ascii is_uni_ascii_lc is_uni_cntrl is_uni_cntrl_lc is_uni_digit is_uni_digit_lc is_uni_graph is_uni_graph_lc is_uni_idfirst is_uni_idfirst_lc is_uni_lower is_uni_lower_lc is_uni_print is_uni_print_lc is_uni_punct is_uni_punct_lc is_uni_space is_uni_space_lc is_uni_upper is_uni_upper_lc is_uni_xdigit is_uni_xdigit_lc is_utf8_alnum is_utf8_alnumc is_utf8_alpha is_utf8_ascii is_utf8_char is_utf8_cntrl is_utf8_digit is_utf8_graph is_utf8_idfirst is_utf8_lower is_utf8_mark is_utf8_print is_utf8_punct is_utf8_space is_utf8_upper is_utf8_xdigit load_module magic_dump mess my_atof my_fflush_all newANONATTRSUB newATTRSUB newMYSUB newPADOP newXS newXSproto new_collate new_ctype new_numeric op_dump perl_parse pmop_dump pv_display re_intuit_start re_intuit_string reginitcolors require_pv safesyscalloc safesysfree safesysmalloc safesysrealloc save_I8 save_alloc save_destructor save_destructor_x save_re_context save_vptr scan_bin set_context set_numeric_local set_numeric_radix set_numeric_standard str_to_version sv_2pvutf8 sv_2pvutf8_nolen sv_force_normal sv_len_utf8 sv_pos_b2u sv_pos_u2b sv_pv sv_pvbyte sv_pvbyten sv_pvbyten_force sv_pvutf8 sv_pvutf8n sv_pvutf8n_force sv_rvweaken sv_utf8_decode sv_utf8_downgrade sv_utf8_encode swash_init tmps_grow to_uni_lower_lc to_uni_title_lc to_uni_upper_lc utf8_distance utf8_hop vcroak vform vload_module vmess vwarn vwarner warner
POPpx get_vtbl save_generic_svref
PL_modglobal cx_dump debop debprofdump fbm_compile fbm_instr get_op_descs get_op_names init_stacks mg_length mg_size newHVhv new_stackinfo regdump regexec_flags regnext runops_debug runops_standard save_hints save_iv save_threadsv screaminstr sv_iv sv_nv sv_peek sv_true
do_binmode save_aelem save_helem
newWHILEOP
GIMME_V G_VOID HEf_SVKEY HeHASH HeKEY HeKLEN HePV HeSVKEY HeSVKEY_force HeSVKEY_set HeVAL SvSetMagicSV SvSetMagicSV_nosteal SvSetSV_nosteal SvTAINTED SvTAINTED_off SvTAINTED_on block_gimme call_list cv_const_sv delimcpy do_open form gv_autoload4 gv_efullname3 gv_fetchmethod_autoload gv_fullname3 hv_delayfree_ent hv_delete_ent hv_exists_ent hv_fetch_ent hv_free_ent hv_iterkeysv hv_ksplit hv_store_ent ibcmp_locale my_failure_exit my_memcmp my_pclose my_popen newSVpvf rsignal rsignal_state save_I16 save_gp start_subparse sv_catpvf sv_catpvf_mg sv_cmp_locale sv_derived_from sv_gets sv_setpvf sv_setpvf_mg sv_taint sv_tainted sv_untaint sv_vcatpvf sv_vcatpvf_mg sv_vcatpvfn sv_vsetpvf sv_vsetpvf_mg sv_vsetpvfn unsharepvn vnewSVpvf
BUGS
If you find any bugs, Devel::PPPort doesn't seem to build on your
system or any of its tests fail, please use the CPAN Request Tracker
at http://rt.cpan.org/ to create a ticket for the module.
AUTHORS
Version 1.x of Devel::PPPort was written by Kenneth Albanowski.
Version 2.x was ported to the Perl core by Paul Marquess.
Version 3.x was ported back to CPAN by Marcus Holland-Moritz.
COPYRIGHT
Version 3.x, Copyright (C) 2004, Marcus Holland-Moritz.
Version 2.x, Copyright (C) 2001, Paul Marquess.
Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
