-- Perl 5.8.6 documentation --
Devel::PPPort

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:

  • perl 5.9.2
  •   SvPVbyte_force
      find_rundefsvoffset
      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

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

See h2xs, ppport.h.