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 two functions, WriteFile
and GetFileContents
.
WriteFile
's 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.20 are supported.

GetFileContents
can be used to retrieve the file contents rather than
writing it out.

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:

perlppport.h[options][files]

It also has embedded documentation, so you can use

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

GetFileContents

GetFileContents
behaves like WriteFile
above, but returns the contents
of the would-be file rather than writing it out.

COMPATIBILITY

ppport.h supports Perl versions from 5.003 to 5.20
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

caller_cx

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_cvn_flags

get_cvs

get_hv

get_sv

grok_bin

grok_hex

grok_number

GROK_NUMERIC_RADIX

grok_numeric_radix

grok_oct

gv_fetchpvn_flags

gv_fetchpvs

gv_fetchsv

gv_stashpvn

gv_stashpvs

GvSVn

HEf_SVKEY

HeUTF8

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

memEQs

memNE

memNEs

mg_findext

MoveD

mPUSHi

mPUSHn

mPUSHp

mPUSHs

mPUSHu

MUTABLE_PTR

MUTABLE_SV

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

newSVpvs_share

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_unmagicext

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_nomg_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

WIDEST_UTYPE

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: