You are viewing the version of this documentation from Perl 5.14.0. View the latest version

CONTENTS

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
CPERLscope
dAX
dAXMARK
DEFSV
DEFSV_set
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
G_METHOD
get_av
get_cv
get_hv
get_sv
grok_bin
grok_hex
grok_number
GROK_NUMERIC_RADIX
grok_numeric_radix
grok_oct
gv_fetchpvn_flags
gv_fetchpvs
gv_stashpvn
gv_stashpvs
GvSVn
hv_fetchs
hv_stores
HvNAME_get
HvNAMELEN_get
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
isALNUMC
isASCII
isBLANK
isCNTRL
isGRAPH
isGV_with_GP
isPRINT
isPSXSPC
isPUNCT
isXDIGIT
IVdf
IVSIZE
IVTYPE
load_module
memEQ
memNE
MoveD
mPUSHi
mPUSHn
mPUSHp
mPUSHs
mPUSHu
mXPUSHi
mXPUSHn
mXPUSHp
mXPUSHs
mXPUSHu
MY_CXT
MY_CXT_CLONE
MY_CXT_INIT
my_snprintf
my_sprintf
my_strlcat
my_strlcpy
newCONSTSUB
newRV_inc
newRV_noinc
newSV_type
newSVpvn
newSVpvn_flags
newSVpvn_share
newSVpvn_utf8
newSVpvs
newSVpvs_flags
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_PV_ESCAPE_ALL
PERL_PV_ESCAPE_FIRSTCHAR
PERL_PV_ESCAPE_NOBACKSLASH
PERL_PV_ESCAPE_NOCLEAR
PERL_PV_ESCAPE_QUOTE
PERL_PV_ESCAPE_RE
PERL_PV_ESCAPE_UNI
PERL_PV_ESCAPE_UNI_DETECT
PERL_PV_PRETTY_DUMP
PERL_PV_PRETTY_ELLIPSES
PERL_PV_PRETTY_LTGT
PERL_PV_PRETTY_NOCLEAR
PERL_PV_PRETTY_QUOTE
PERL_PV_PRETTY_REGPROP
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
PERLIO_FUNCS_CAST
PERLIO_FUNCS_DECL
PL_bufend
PL_bufptr
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_error_count
PL_expect
PL_hexdigit
PL_hints
PL_in_my
PL_in_my_stash
PL_laststatval
PL_lex_state
PL_lex_stuff
PL_linestr
PL_na
PL_no_modify
PL_parser
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
PL_tokenbuf
pMY_CXT
pMY_CXT_
Poison
PoisonFree
PoisonNew
PoisonWith
pTHX
pTHX_
PTR2IV
PTR2nat
PTR2NV
PTR2ul
PTR2UV
PTRV
PUSHmortal
PUSHu
pv_display
pv_escape
pv_pretty
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
SVf_UTF8
SVfARG
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
SvPV_renew
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
XSPROTO
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.11.0
HeUTF8
MULTICALL
PERL_SYS_TERM
POP_MULTICALL
PUSH_MULTICALL
SvOOK_offset
av_iter_p
croak_xs_usage
fetch_cop_label
gv_fetchmethod_flags
hv_assert
mro_get_from_name
mro_get_private_data
mro_register
mro_set_mro
mro_set_private_data
pad_sv
pregfree2
ref
save_adelete
save_helem_flags
save_padsv_and_mortalize
save_pushptr
stashpv_hvname_match
sv_insert_flags
sv_utf8_upgrade_flags_grow
perl 5.10.0
hv_common
hv_common_key_len
sv_destroyable
sys_init
sys_init3
sys_term
perl 5.9.5
Perl_signbit
SvRX
SvRXOK
av_create_and_push
av_create_and_unshift_one
get_cvn_flags
gv_fetchfile_flags
mro_get_linear_isa
mro_method_changed_in
my_dirfd
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
regfree_internal
savesharedpvn
scan_vstring
upg_version
perl 5.9.4
PerlIO_context_layers
gv_name_set
my_vsnprintf
newXS_flags
regclass_swash
sv_does
sv_usepvn_flags
perl 5.9.3
av_arylen_p
ckwarn
ckwarn_d
csighandler
dMULTICALL
doref
gv_const_sv
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
newGIVENOP
newSVhek
newSVpvs_share
newWHENOP
newWHILEOP
savepvs
sortsv_flags
vverify
perl 5.9.2
SvPVbyte_force
find_rundefsvoffset
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
sv_utf8_upgrade_nomg
swash_fetch
perl 5.7.1
POPpbytex
bytes_from_utf8
despatch_signals
do_openn
gv_handler
is_lvalue_sub
my_popen_list
save_mortalizesv
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
PERL_SYS_INIT3
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
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_iv
screaminstr
sv_iv
sv_nv
sv_peek
sv_pvn
sv_pvn_nomg
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-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

See h2xs, ppport.h.