You are viewing the version of this documentation from Perl 5.8.6. 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.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

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1204:

=cut found outside a pod block. Skipping to next block.