Devel::PPPort - Perl/Pollution/Portability

    Devel::PPPort::WriteFile();   # defaults to ./ppport.h
    Devel::PPPort::WriteFile('someheader.h');

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.

CWDevel::PPPort contains a single function, called CWWriteFile. 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 CWh2xs to write the file 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.

Don't direct the users of your module to download CWDevel::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 CWDevel::PPPort release from CPAN), copy it into your project, adjust your project to use it, and distribute the header along with your module.

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

It also has embedded documentation, so you can use

    perldoc ppport.h

to find out more about how to use it.

CWWriteFile 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.

ppport.h supports Perl versions from 5.003 to 5.9.2 in threaded and non-threaded configurations.

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
    dXCPT
    dXSTARG
    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
    XCPT_CATCH
    XCPT_RETHROW
    XCPT_TRY_END
    XCPT_TRY_START
    XPUSHmortal
    XPUSHu
    XSRETURN_UV
    XST_mUV
    ZeroD

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:

perl 5.9.2

  SvPVbyte_force
  find_rundefsvoffset
  gv_fetchpvn_flags
  gv_fetchsv
  op_refcnt_lock
  op_refcnt_unlock
  savesvpv
  vnormal

perl 5.9.1

  hv_assert
  hv_clear_placeholders
  hv_scalar
  scan_version
  sv_2iv_flags
  sv_2uv_flags

perl 5.9.0

  new_version
  save_set_svflags
  upg_version
  vcmp
  vnumify
  vstringify

perl 5.8.3

  SvIsCOW
  SvIsCOW_shared_hash

perl 5.8.1

  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

perl 5.8.0

  hv_iternext_flags
  hv_store_flags
  is_utf8_idcont
  nothreadhook

perl 5.7.3

  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

perl 5.7.2

  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

perl 5.7.1

  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

perl 5.6.1

  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

perl 5.6.0

  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

perl 5.005_03

  POPpx
  get_vtbl
  save_generic_svref

perl 5.005

  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

perl 5.004_05

  do_binmode
  save_aelem
  save_helem

perl 5.004_04

  newWHILEOP

perl 5.004

  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

If you find any bugs, CWDevel::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.

•

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.

Version 3.x, Copyright (C) 2004-2005, 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 h2xs, ppport.h.