Devel::PPPort - Perl/Pollution/Portability


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.10.0 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 [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 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.10.0 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_
    aTHXR
    aTHXR_
    AvFILLp
    boolSV
    call_argv
    call_method
    call_pv
    call_sv
    ckWARN
    CopFILE
    CopFILE_set
    CopFILEAV
    CopFILEGV
    CopFILEGV_set
    CopFILESV
    CopSTASH
    CopSTASH_eq
    CopSTASH_set
    CopSTASHPV
    CopSTASHPV_set
    CopyD
    dAX
    dAXMARK
    DEFSV
    dITEMS
    dMY_CXT
    dMY_CXT_SV
    dNOOP
    dTHR
    dTHX
    dTHXa
    dTHXoa
    dTHXR
    dUNDERBAR
    dVAR
    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
    hv_fetchs
    hv_stores
    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
    load_module
    memEQ
    memNE
    MoveD
    mPUSHi
    mPUSHn
    mPUSHp
    mPUSHu
    mXPUSHi
    mXPUSHn
    mXPUSHp
    mXPUSHu
    MY_CXT
    MY_CXT_CLONE
    MY_CXT_INIT
    my_snprintf
    my_strlcat
    my_strlcpy
    newCONSTSUB
    newRV_inc
    newRV_noinc
    newSVpvn
    newSVpvn_share
    newSVpvs
    newSVuv
    Newx
    Newxc
    Newxz
    NOOP
    NUM2PTR
    NVef
    NVff
    NVgf
    NVTYPE
    packWARN
    PERL_ABS
    PERL_BCDVERSION
    PERL_GCC_BRACE_GROUPS_FORBIDDEN
    PERL_HASH
    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_SIGNALS_UNSAFE_FLAG
    PERL_SUBVERSION
    PERL_UCHAR_MAX
    PERL_UCHAR_MIN
    PERL_UINT_MAX
    PERL_UINT_MIN
    PERL_ULONG_MAX
    PERL_ULONG_MIN
    PERL_UNUSED_ARG
    PERL_UNUSED_CONTEXT
    PERL_UNUSED_DECL
    PERL_UNUSED_VAR
    PERL_UQUAD_MAX
    PERL_UQUAD_MIN
    PERL_USE_GCC_BRACE_GROUPS
    PERL_USHORT_MAX
    PERL_USHORT_MIN
    PERL_VERSION
    Perl_warner
    Perl_warner_nocontext
    PL_compiling
    PL_copline
    PL_curcop
    PL_curstash
    PL_DBsignal
    PL_DBsingle
    PL_DBsub
    PL_DBtrace
    PL_debstash
    PL_defgv
    PL_diehook
    PL_dirty
    PL_dowarn
    PL_errgv
    PL_expect
    PL_hexdigit
    PL_hints
    PL_laststatval
    PL_na
    PL_no_modify
    PL_perl_destruct_level
    PL_perldb
    PL_ppaddr
    PL_rsfp
    PL_rsfp_filters
    PL_signals
    PL_stack_base
    PL_stack_sp
    PL_statcache
    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
    PoisonFree
    PoisonNew
    PoisonWith
    pTHX
    pTHX_
    PTR2IV
    PTR2NV
    PTR2ul
    PTR2UV
    PTRV
    PUSHmortal
    PUSHu
    SAVE_DEFSV
    START_EXTERN_C
    START_MY_CXT
    STMT_END
    STMT_START
    STR_WITH_LEN
    sv_2pv_flags
    sv_2pv_nolen
    sv_2pvbyte
    sv_2pvbyte_nolen
    sv_2uv
    sv_catpv_mg
    sv_catpvf_mg
    sv_catpvf_mg_nocontext
    sv_catpvn_mg
    sv_catpvn_nomg
    sv_catpvs
    sv_catsv_mg
    sv_catsv_nomg
    SV_CONST_RETURN
    SV_COW_DROP_PV
    SV_COW_SHARED_HASH_KEYS
    SV_GMAGIC
    SV_HAS_TRAILING_NUL
    SV_IMMEDIATE_UNREF
    sv_magic_portable
    SV_MUTABLE_RETURN
    SV_NOSTEAL
    sv_pvn_force_flags
    sv_pvn_nomg
    sv_setiv_mg
    sv_setnv_mg
    sv_setpv_mg
    sv_setpvf_mg
    sv_setpvf_mg_nocontext
    sv_setpvn_mg
    sv_setpvs
    sv_setsv_mg
    sv_setsv_nomg
    sv_setuv
    sv_setuv_mg
    SV_SMAGIC
    sv_usepvn_mg
    SV_UTF8_NO_ENCODING
    sv_uv
    sv_vcatpvf
    sv_vcatpvf_mg
    sv_vsetpvf
    sv_vsetpvf_mg
    SVf
    SvGETMAGIC
    SvIV_nomg
    SvMAGIC_set
    SvPV_const
    SvPV_flags
    SvPV_flags_const
    SvPV_flags_const_nolen
    SvPV_flags_mutable
    SvPV_force
    SvPV_force_flags
    SvPV_force_flags_mutable
    SvPV_force_flags_nolen
    SvPV_force_mutable
    SvPV_force_nolen
    SvPV_force_nomg
    SvPV_force_nomg_nolen
    SvPV_mutable
    SvPV_nolen
    SvPV_nolen_const
    SvPV_nomg
    SvPV_nomg_const
    SvPV_nomg_const_nolen
    SvPVbyte
    SvPVX_const
    SvPVX_mutable
    SvREFCNT_inc
    SvREFCNT_inc_NN
    SvREFCNT_inc_simple
    SvREFCNT_inc_simple_NN
    SvREFCNT_inc_simple_void
    SvREFCNT_inc_simple_void_NN
    SvREFCNT_inc_void
    SvREFCNT_inc_void_NN
    SvRV_set
    SvSHARED_HASH
    SvSTASH_set
    SvUOK
    SvUV
    SvUV_nomg
    SvUV_set
    SvUVX
    SvUVx
    SvUVXx
    SvVSTRING_mg
    UNDERBAR
    UTF8_MAXBYTES
    UVof
    UVSIZE
    UVTYPE
    UVuf
    UVXf
    UVxf
    vload_module
    vnewSVpvf
    WARN_ALL
    WARN_AMBIGUOUS
    WARN_ASSERTIONS
    WARN_BAREWORD
    WARN_CLOSED
    WARN_CLOSURE
    WARN_DEBUGGING
    WARN_DEPRECATED
    WARN_DIGIT
    WARN_EXEC
    WARN_EXITING
    WARN_GLOB
    WARN_INPLACE
    WARN_INTERNAL
    WARN_IO
    WARN_LAYER
    WARN_MALLOC
    WARN_MISC
    WARN_NEWLINE
    WARN_NUMERIC
    WARN_ONCE
    WARN_OVERFLOW
    WARN_PACK
    WARN_PARENTHESIS
    WARN_PIPE
    WARN_PORTABLE
    WARN_PRECEDENCE
    WARN_PRINTF
    WARN_PROTOTYPE
    WARN_QW
    WARN_RECURSION
    WARN_REDEFINE
    WARN_REGEXP
    WARN_RESERVED
    WARN_SEMICOLON
    WARN_SEVERE
    WARN_SIGNAL
    WARN_SUBSTR
    WARN_SYNTAX
    WARN_TAINT
    WARN_THREADS
    WARN_UNINITIALIZED
    WARN_UNOPENED
    WARN_UNPACK
    WARN_UNTIE
    WARN_UTF8
    WARN_VOID
    warner
    XCPT_CATCH
    XCPT_RETHROW
    XCPT_TRY_END
    XCPT_TRY_START
    XPUSHmortal
    XPUSHu
    XSprePUSH
    XSRETURN
    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:

perl 5.9.5
  MULTICALL
  POP_MULTICALL
  PUSH_MULTICALL
  Perl_signbit
  SvRX
  SvRXOK
  av_create_and_push
  av_create_and_unshift_one
  get_cvn_flags
  gv_fetchfile_flags
  hv_assert
  mro_get_linear_isa
  mro_get_linear_isa_c3
  mro_get_linear_isa_dfs
  mro_method_changed_in
  my_dirfd
  newSV_type
  pad_sv
  pregcomp
  ptr_table_clear
  ptr_table_fetch
  ptr_table_free
  ptr_table_new
  ptr_table_split
  ptr_table_store
  re_compile
  re_intuit_start
  reg_named_buff_all
  reg_named_buff_exists
  reg_named_buff_fetch
  reg_named_buff_firstkey
  reg_named_buff_nextkey
  reg_named_buff_scalar
  reg_stringify
  regfree_internal
  savesharedpvn
  scan_vstring
  stashpv_hvname_match
  upg_version
perl 5.9.4
  PerlIO_context_layers
  gv_name_set
  my_vsnprintf
  newXS_flags
  pv_escape
  pv_pretty
  regclass_swash
  sv_does
  sv_usepvn_flags
perl 5.9.3
  av_arylen_p
  ckwarn
  ckwarn_d
  csighandler
  dMULTICALL
  doref
  gv_const_sv
  gv_stashpvs
  hv_eiter_p
  hv_eiter_set
  hv_name_set
  hv_placeholders_get
  hv_placeholders_p
  hv_placeholders_set
  hv_riter_p
  hv_riter_set
  is_utf8_string_loclen
  my_sprintf
  newGIVENOP
  newSVhek
  newSVpvs_share
  newWHENOP
  newWHILEOP
  ref
  savepvs
  sortsv_flags
  vverify
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_clear_placeholders
  hv_scalar
  scan_version
  sv_2iv_flags
  sv_2uv_flags
perl 5.9.0
  new_version
  save_set_svflags
  vcmp
  vnumify
  vstringify
perl 5.8.3
  SvIsCOW
  SvIsCOW_shared_hash
perl 5.8.1
  SvVOK
  doing_taint
  find_runcv
  is_utf8_string_loc
  packlist
  save_bool
  savestack_grow_cnt
  seed
  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
  save_shared_pvref
  savesharedpv
  sortsv
  sv_copypv
  sv_magicext
  sv_nolocking
  sv_nosharing
  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_catpvn_flags
  sv_catsv_flags
  sv_setsv_flags
  sv_utf8_upgrade_flags
  swash_fetch
perl 5.7.1
  POPpbytex
  bytes_from_utf8
  despatch_signals
  do_openn
  gv_handler
  is_lvalue_sub
  my_popen_list
  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_uvuni
  uvuni_to_utf8
perl 5.6.1
  SvGAMAGIC
  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
  SvUOK
  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
  magic_dump
  mess
  my_atof
  my_fflush_all
  newANONATTRSUB
  newATTRSUB
  newXS
  newXSproto
  new_collate
  new_ctype
  new_numeric
  op_dump
  perl_parse
  pmop_dump
  pv_display
  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
  vmess
  vwarn
  vwarner
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
  screaminstr
  sv_iv
  sv_nv
  sv_peek
  sv_true
perl 5.004_05
  do_binmode
  save_aelem
  save_helem
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
  share_hek
  start_subparse
  sv_catpvf
  sv_catpvf_mg
  sv_cmp_locale
  sv_derived_from
  sv_gets
  sv_magic_portable
  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
  warner


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


COPYRIGHT

Version 3.x, Copyright (C) 2004-2007, 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

See h2xs, ppport.h.

 Devel::PPPort - Perl/Pollution/Portability