CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • Why use ppport.h?
  • How to use ppport.h
  • Running ppport.h
• FUNCTIONS
  • WriteFile
• COMPATIBILITY
  • Provided Perl compatibility API
  • Perl API not supported by ppport.h
• BUGS
• AUTHORS
• COPYRIGHT
• SEE ALSO

#NAME

Devel::PPPort - Perl/Pollution/Portability

#SYNOPSIS

Devel::PPPort::WriteFile();   # defaults to ./ppport.hDevel::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, typicallyppport.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, calledWriteFile. Its only purpose is to write theppport.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.10.0 are supported.

This module is used byh2xs to write the fileppport.h.

#Why use ppport.h?

You should useppport.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 useppport.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 downloadDevel::PPPort. They are most probably no XS writers. Also, don't makeppport.h optional. Rather, just take the most recent copy ofppport.h that you can find (e.g. by generating it with the latestDevel::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

Butppport.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 [options] [files]

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 filenameppport.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.10.0 in threaded and non-threaded configurations.

#Provided Perl compatibility API

The header file written by this module, typicallyppport.h, provides access to the following elements of the Perl API that is not available in older Perl releases:

_aMY_CXT_pMY_CXTaMY_CXTaMY_CXT_aTHXaTHX_aTHXRaTHXR_AvFILLpboolSVcall_argvcall_methodcall_pvcall_svckWARNCopFILECopFILE_setCopFILEAVCopFILEGVCopFILEGV_setCopFILESVCopSTASHCopSTASH_eqCopSTASH_setCopSTASHPVCopSTASHPV_setCopyDCPERLscopedAXdAXMARKDEFSVDEFSV_setdITEMSdMY_CXTdMY_CXT_SVdNOOPdTHRdTHXdTHXadTHXoadTHXRdUNDERBARdVARdXCPTdXSTARGEND_EXTERN_CERRSVeval_pveval_svEXTERN_CG_METHODget_avget_cvget_hvget_svgrok_bingrok_hexgrok_numberGROK_NUMERIC_RADIXgrok_numeric_radixgrok_octgv_fetchpvn_flagsgv_fetchpvsgv_stashpvngv_stashpvsGvSVnhv_fetchshv_storesHvNAME_getHvNAMELEN_getIN_LOCALEIN_LOCALE_COMPILETIMEIN_LOCALE_RUNTIMEIN_PERL_COMPILETIMEINT2PTRIS_NUMBER_GREATER_THAN_UV_MAXIS_NUMBER_IN_UVIS_NUMBER_INFINITYIS_NUMBER_NANIS_NUMBER_NEGIS_NUMBER_NOT_INTisALNUMCisASCIIisBLANKisCNTRLisGRAPHisGV_with_GPisPRINTisPSXSPCisPUNCTisXDIGITIVdfIVSIZEIVTYPEload_modulememEQmemNEMoveDmPUSHimPUSHnmPUSHpmPUSHsmPUSHumXPUSHimXPUSHnmXPUSHpmXPUSHsmXPUSHuMY_CXTMY_CXT_CLONEMY_CXT_INITmy_snprintfmy_sprintfmy_strlcatmy_strlcpynewCONSTSUBnewRV_incnewRV_noincnewSV_typenewSVpvnnewSVpvn_flagsnewSVpvn_sharenewSVpvn_utf8newSVpvsnewSVpvs_flagsnewSVuvNewxNewxcNewxzNOOPNUM2PTRNVefNVffNVgfNVTYPEpackWARNPERL_ABSPERL_BCDVERSIONPERL_GCC_BRACE_GROUPS_FORBIDDENPERL_HASHPERL_INT_MAXPERL_INT_MINPERL_LONG_MAXPERL_LONG_MINPERL_MAGIC_arylenPERL_MAGIC_backrefPERL_MAGIC_bmPERL_MAGIC_collxfrmPERL_MAGIC_dbfilePERL_MAGIC_dblinePERL_MAGIC_defelemPERL_MAGIC_envPERL_MAGIC_envelemPERL_MAGIC_extPERL_MAGIC_fmPERL_MAGIC_globPERL_MAGIC_isaPERL_MAGIC_isaelemPERL_MAGIC_mutexPERL_MAGIC_nkeysPERL_MAGIC_overloadPERL_MAGIC_overload_elemPERL_MAGIC_overload_tablePERL_MAGIC_posPERL_MAGIC_qrPERL_MAGIC_regdataPERL_MAGIC_regdatumPERL_MAGIC_regex_globalPERL_MAGIC_sharedPERL_MAGIC_shared_scalarPERL_MAGIC_sigPERL_MAGIC_sigelemPERL_MAGIC_substrPERL_MAGIC_svPERL_MAGIC_taintPERL_MAGIC_tiedPERL_MAGIC_tiedelemPERL_MAGIC_tiedscalarPERL_MAGIC_utf8PERL_MAGIC_uvarPERL_MAGIC_uvar_elemPERL_MAGIC_vecPERL_MAGIC_vstringPERL_PV_ESCAPE_ALLPERL_PV_ESCAPE_FIRSTCHARPERL_PV_ESCAPE_NOBACKSLASHPERL_PV_ESCAPE_NOCLEARPERL_PV_ESCAPE_QUOTEPERL_PV_ESCAPE_REPERL_PV_ESCAPE_UNIPERL_PV_ESCAPE_UNI_DETECTPERL_PV_PRETTY_DUMPPERL_PV_PRETTY_ELLIPSESPERL_PV_PRETTY_LTGTPERL_PV_PRETTY_NOCLEARPERL_PV_PRETTY_QUOTEPERL_PV_PRETTY_REGPROPPERL_QUAD_MAXPERL_QUAD_MINPERL_REVISIONPERL_SCAN_ALLOW_UNDERSCORESPERL_SCAN_DISALLOW_PREFIXPERL_SCAN_GREATER_THAN_UV_MAXPERL_SCAN_SILENT_ILLDIGITPERL_SHORT_MAXPERL_SHORT_MINPERL_SIGNALS_UNSAFE_FLAGPERL_SUBVERSIONPERL_UCHAR_MAXPERL_UCHAR_MINPERL_UINT_MAXPERL_UINT_MINPERL_ULONG_MAXPERL_ULONG_MINPERL_UNUSED_ARGPERL_UNUSED_CONTEXTPERL_UNUSED_DECLPERL_UNUSED_VARPERL_UQUAD_MAXPERL_UQUAD_MINPERL_USE_GCC_BRACE_GROUPSPERL_USHORT_MAXPERL_USHORT_MINPERL_VERSIONPerl_warnerPerl_warner_nocontextPERLIO_FUNCS_CASTPERLIO_FUNCS_DECLPL_bufendPL_bufptrPL_compilingPL_coplinePL_curcopPL_curstashPL_DBsignalPL_DBsinglePL_DBsubPL_DBtracePL_debstashPL_defgvPL_diehookPL_dirtyPL_dowarnPL_errgvPL_error_countPL_expectPL_hexdigitPL_hintsPL_in_myPL_in_my_stashPL_laststatvalPL_lex_statePL_lex_stuffPL_linestrPL_naPL_no_modifyPL_parserPL_perl_destruct_levelPL_perldbPL_ppaddrPL_rsfpPL_rsfp_filtersPL_signalsPL_stack_basePL_stack_spPL_statcachePL_stdingvPL_SvPL_sv_arenarootPL_sv_noPL_sv_undefPL_sv_yesPL_taintedPL_taintingPL_tokenbufpMY_CXTpMY_CXT_PoisonPoisonFreePoisonNewPoisonWithpTHXpTHX_PTR2IVPTR2natPTR2NVPTR2ulPTR2UVPTRVPUSHmortalPUSHupv_displaypv_escapepv_prettySAVE_DEFSVSTART_EXTERN_CSTART_MY_CXTSTMT_ENDSTMT_STARTSTR_WITH_LENsv_2pv_flagssv_2pv_nolensv_2pvbytesv_2pvbyte_nolensv_2uvsv_catpv_mgsv_catpvf_mgsv_catpvf_mg_nocontextsv_catpvn_mgsv_catpvn_nomgsv_catpvssv_catsv_mgsv_catsv_nomgSV_CONST_RETURNSV_COW_DROP_PVSV_COW_SHARED_HASH_KEYSSV_GMAGICSV_HAS_TRAILING_NULSV_IMMEDIATE_UNREFsv_magic_portableSV_MUTABLE_RETURNSV_NOSTEALsv_pvn_force_flagssv_pvn_nomgsv_setiv_mgsv_setnv_mgsv_setpv_mgsv_setpvf_mgsv_setpvf_mg_nocontextsv_setpvn_mgsv_setpvssv_setsv_mgsv_setsv_nomgsv_setuvsv_setuv_mgSV_SMAGICsv_usepvn_mgSV_UTF8_NO_ENCODINGsv_uvsv_vcatpvfsv_vcatpvf_mgsv_vsetpvfsv_vsetpvf_mgSVfSVf_UTF8SVfARGSvGETMAGICSvIV_nomgSvMAGIC_setSvPV_constSvPV_flagsSvPV_flags_constSvPV_flags_const_nolenSvPV_flags_mutableSvPV_forceSvPV_force_flagsSvPV_force_flags_mutableSvPV_force_flags_nolenSvPV_force_mutableSvPV_force_nolenSvPV_force_nomgSvPV_force_nomg_nolenSvPV_mutableSvPV_nolenSvPV_nolen_constSvPV_nomgSvPV_nomg_constSvPV_nomg_const_nolenSvPV_renewSvPVbyteSvPVX_constSvPVX_mutableSvREFCNT_incSvREFCNT_inc_NNSvREFCNT_inc_simpleSvREFCNT_inc_simple_NNSvREFCNT_inc_simple_voidSvREFCNT_inc_simple_void_NNSvREFCNT_inc_voidSvREFCNT_inc_void_NNSvRV_setSvSHARED_HASHSvSTASH_setSvUOKSvUVSvUV_nomgSvUV_setSvUVXSvUVxSvUVXxSvVSTRING_mgUNDERBARUTF8_MAXBYTESUVofUVSIZEUVTYPEUVufUVXfUVxfvload_modulevnewSVpvfWARN_ALLWARN_AMBIGUOUSWARN_ASSERTIONSWARN_BAREWORDWARN_CLOSEDWARN_CLOSUREWARN_DEBUGGINGWARN_DEPRECATEDWARN_DIGITWARN_EXECWARN_EXITINGWARN_GLOBWARN_INPLACEWARN_INTERNALWARN_IOWARN_LAYERWARN_MALLOCWARN_MISCWARN_NEWLINEWARN_NUMERICWARN_ONCEWARN_OVERFLOWWARN_PACKWARN_PARENTHESISWARN_PIPEWARN_PORTABLEWARN_PRECEDENCEWARN_PRINTFWARN_PROTOTYPEWARN_QWWARN_RECURSIONWARN_REDEFINEWARN_REGEXPWARN_RESERVEDWARN_SEMICOLONWARN_SEVEREWARN_SIGNALWARN_SUBSTRWARN_SYNTAXWARN_TAINTWARN_THREADSWARN_UNINITIALIZEDWARN_UNOPENEDWARN_UNPACKWARN_UNTIEWARN_UTF8WARN_VOIDwarnerXCPT_CATCHXCPT_RETHROWXCPT_TRY_ENDXCPT_TRY_STARTXPUSHmortalXPUSHuXSprePUSHXSPROTOXSRETURNXSRETURN_UVXST_mUVZeroD

#Perl API not supported by ppport.h

There is still a big part of the API not supported byppport.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:

#perl 5.11.0

HeUTF8MULTICALLPERL_SYS_TERMPOP_MULTICALLPUSH_MULTICALLSvOOK_offsetav_iter_pcroak_xs_usagefetch_cop_labelgv_fetchmethod_flagshv_assertmro_get_from_namemro_get_private_datamro_registermro_set_mromro_set_private_datapad_svpregfree2refsave_adeletesave_helem_flagssave_padsv_and_mortalizesave_pushptrstashpv_hvname_matchsv_insert_flagssv_utf8_upgrade_flags_grow

#perl 5.10.0

hv_commonhv_common_key_lensv_destroyablesys_initsys_init3sys_term

#perl 5.9.5

Perl_signbitSvRXSvRXOKav_create_and_pushav_create_and_unshift_oneget_cvn_flagsgv_fetchfile_flagsmro_get_linear_isamro_method_changed_inmy_dirfdpregcompptr_table_clearptr_table_fetchptr_table_freeptr_table_newptr_table_splitptr_table_storere_compilere_intuit_startreg_named_buff_allreg_named_buff_existsreg_named_buff_fetchreg_named_buff_firstkeyreg_named_buff_nextkeyreg_named_buff_scalarregfree_internalsavesharedpvnscan_vstringupg_version

#perl 5.9.4

PerlIO_context_layersgv_name_setmy_vsnprintfnewXS_flagsregclass_swashsv_doessv_usepvn_flags

#perl 5.9.3

av_arylen_pckwarnckwarn_dcsighandlerdMULTICALLdorefgv_const_svhv_eiter_phv_eiter_sethv_name_sethv_placeholders_gethv_placeholders_phv_placeholders_sethv_riter_phv_riter_setis_utf8_string_loclennewGIVENOPnewSVheknewSVpvs_sharenewWHENOPnewWHILEOPsavepvssortsv_flagsvverify

#perl 5.9.2

SvPVbyte_forcefind_rundefsvoffsetgv_fetchsvop_refcnt_lockop_refcnt_unlocksavesvpvvnormal

#perl 5.9.1

hv_clear_placeholdershv_scalarscan_versionsv_2iv_flagssv_2uv_flags

#perl 5.9.0

new_versionsave_set_svflagsvcmpvnumifyvstringify

#perl 5.8.3

SvIsCOWSvIsCOW_shared_hash

#perl 5.8.1

SvVOKdoing_taintfind_runcvis_utf8_string_locpacklistsave_boolsavestack_grow_cntseedsv_cat_decodesv_compile_2opsv_setpvivsv_setpviv_mgunpackstring

#perl 5.8.0

hv_iternext_flagshv_store_flagsis_utf8_idcontnothreadhook

#perl 5.7.3

PerlIO_clearerrPerlIO_closePerlIO_eofPerlIO_errorPerlIO_filenoPerlIO_fillPerlIO_flushPerlIO_get_basePerlIO_get_bufsizPerlIO_get_cntPerlIO_get_ptrPerlIO_readPerlIO_seekPerlIO_set_cntPerlIO_set_ptrcntPerlIO_setlinebufPerlIO_stderrPerlIO_stdinPerlIO_stdoutPerlIO_tellPerlIO_unreadPerlIO_writeSvLOCKSvSHARESvUNLOCKatfork_lockatfork_unlockcustom_op_desccustom_op_namedebdebstackdebstackptrsgv_fetchmeth_autoloadibcmp_utf8my_forkmy_socketpairpack_catperl_destructpv_uni_displaysave_shared_pvrefsavesharedpvsortsvsv_copypvsv_magicextsv_nolockingsv_nosharingsv_recode_to_utf8sv_uni_displayto_uni_foldto_uni_lowerto_uni_titleto_uni_upperto_utf8_caseto_utf8_foldto_utf8_lowerto_utf8_titleto_utf8_upperunpack_struvchr_to_utf8_flagsuvuni_to_utf8_flagsvdeb

#perl 5.7.2

callocgetcwd_svinit_tmmallocmfreemini_mktimemy_atof2my_strftimeop_nullreallocsv_catpvn_flagssv_catsv_flagssv_setsv_flagssv_utf8_upgrade_flagssv_utf8_upgrade_nomgswash_fetch

#perl 5.7.1

POPpbytexbytes_from_utf8despatch_signalsdo_openngv_handleris_lvalue_submy_popen_listsave_mortalizesvscan_numsv_force_normal_flagssv_setref_uvsv_unref_flagssv_utf8_upgradeutf8_lengthutf8_to_uvchrutf8_to_uvuniutf8n_to_uvuniuvuni_to_utf8

#perl 5.6.1

SvGAMAGICapply_attrs_stringbytes_to_utf8gv_efullname4gv_fullname4is_utf8_stringsave_generic_pvrefutf16_to_utf8utf16_to_utf8_reversedutf8_to_bytes

#perl 5.6.0

PERL_SYS_INIT3SvIOK_UVSvIOK_notUVSvIOK_only_UVSvPOK_only_UTF8SvPVbyte_nolenSvPVbytexSvPVbytex_forceSvPVutf8SvPVutf8_forceSvPVutf8_nolenSvPVutf8xSvPVutf8x_forceSvUOKSvUTF8SvUTF8_offSvUTF8_onav_deleteav_existscall_atexitcast_i32cast_ivcast_ulongcast_uvdo_gv_dumpdo_gvgv_dumpdo_hv_dumpdo_magic_dumpdo_op_dumpdo_open9do_pmop_dumpdo_sv_dumpdump_alldump_evaldump_formdump_indentdump_packsubsdump_subdump_vindentget_contextget_ppaddrgv_dumpinit_i18nl10ninit_i18nl14nis_uni_alnumis_uni_alnum_lcis_uni_alnumcis_uni_alnumc_lcis_uni_alphais_uni_alpha_lcis_uni_asciiis_uni_ascii_lcis_uni_cntrlis_uni_cntrl_lcis_uni_digitis_uni_digit_lcis_uni_graphis_uni_graph_lcis_uni_idfirstis_uni_idfirst_lcis_uni_loweris_uni_lower_lcis_uni_printis_uni_print_lcis_uni_punctis_uni_punct_lcis_uni_spaceis_uni_space_lcis_uni_upperis_uni_upper_lcis_uni_xdigitis_uni_xdigit_lcis_utf8_alnumis_utf8_alnumcis_utf8_alphais_utf8_asciiis_utf8_charis_utf8_cntrlis_utf8_digitis_utf8_graphis_utf8_idfirstis_utf8_loweris_utf8_markis_utf8_printis_utf8_punctis_utf8_spaceis_utf8_upperis_utf8_xdigitmagic_dumpmessmy_atofmy_fflush_allnewANONATTRSUBnewATTRSUBnewXSnewXSprotonew_collatenew_ctypenew_numericop_dumpperl_parsepmop_dumpre_intuit_stringreginitcolorsrequire_pvsafesyscallocsafesysfreesafesysmallocsafesysreallocsave_I8save_allocsave_destructorsave_destructor_xsave_re_contextsave_vptrscan_binset_contextset_numeric_localset_numeric_radixset_numeric_standardstr_to_versionsv_2pvutf8sv_2pvutf8_nolensv_force_normalsv_len_utf8sv_pos_b2usv_pos_u2bsv_pvsv_pvbytesv_pvbytensv_pvbyten_forcesv_pvutf8sv_pvutf8nsv_pvutf8n_forcesv_rvweakensv_utf8_decodesv_utf8_downgradesv_utf8_encodeswash_inittmps_growto_uni_lower_lcto_uni_title_lcto_uni_upper_lcutf8_distanceutf8_hopvcroakvformvmessvwarnvwarner

#perl 5.005_03

POPpxget_vtblsave_generic_svref

#perl 5.005

PL_modglobalcx_dumpdebopdebprofdumpfbm_compilefbm_instrget_op_descsget_op_namesinit_stacksmg_lengthmg_sizenewHVhvnew_stackinforegdumpregexec_flagsregnextrunops_debugrunops_standardsave_ivscreaminstrsv_ivsv_nvsv_peeksv_pvnsv_pvn_nomgsv_true

#perl 5.004_05

do_binmodesave_aelemsave_helem

#perl 5.004

GIMME_VG_VOIDHEf_SVKEYHeHASHHeKEYHeKLENHePVHeSVKEYHeSVKEY_forceHeSVKEY_setHeVALSvSetMagicSVSvSetMagicSV_nostealSvSetSV_nostealSvTAINTEDSvTAINTED_offSvTAINTED_onblock_gimmecall_listcv_const_svdelimcpydo_openformgv_autoload4gv_efullname3gv_fetchmethod_autoloadgv_fullname3hv_delayfree_enthv_delete_enthv_exists_enthv_fetch_enthv_free_enthv_iterkeysvhv_ksplithv_store_entibcmp_localemy_failure_exitmy_memcmpmy_pclosemy_popennewSVpvfrsignalrsignal_statesave_I16save_gpshare_hekstart_subparsesv_catpvfsv_catpvf_mgsv_cmp_localesv_derived_fromsv_getssv_magic_portablesv_setpvfsv_setpvf_mgsv_taintsv_taintedsv_untaintsv_vcatpvfsv_vcatpvf_mgsv_vcatpvfnsv_vsetpvfsv_vsetpvf_mgsv_vsetpvfnunsharepvnvnewSVpvfwarner

#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 athttp://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-2009, 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

Seeh2xs,ppport.h.

Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.

The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.