1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
132 .TH PPPort 3 "2009-06-14" "perl v5.8.7" "User Contributed Perl Documentation"
134 Devel::PPPort \- Perl/Pollution/Portability
136 .IX Header "SYNOPSIS"
138 \& Devel::PPPort::WriteFile(); # defaults to ./ppport.h
139 \& Devel::PPPort::WriteFile('someheader.h');
142 .IX Header "DESCRIPTION"
143 Perl's \s-1API\s0 has changed over time, gaining new features, new functions,
144 increasing its flexibility, and reducing the impact on the C namespace
145 environment (reduced pollution). The header file written by this module,
146 typically \fIppport.h\fR, attempts to bring some of the newer Perl \s-1API\s0
147 features to older versions of Perl, so that you can worry less about
148 keeping track of old releases, but users can still reap the benefit.
150 \&\f(CW\*(C`Devel::PPPort\*(C'\fR contains a single function, called \f(CW\*(C`WriteFile\*(C'\fR. Its
151 only purpose is to write the \fIppport.h\fR C header file. This file
152 contains a series of macros and, if explicitly requested, functions that
153 allow \s-1XS\s0 modules to be built using older versions of Perl. Currently,
154 Perl versions from 5.003 to 5.10.0 are supported.
156 This module is used by \f(CW\*(C`h2xs\*(C'\fR to write the file \fIppport.h\fR.
157 .Sh "Why use ppport.h?"
158 .IX Subsection "Why use ppport.h?"
159 You should use \fIppport.h\fR in modern code so that your code will work
160 with the widest range of Perl interpreters possible, without significant
163 You should attempt older code to fully use \fIppport.h\fR, because the
164 reduced pollution of newer Perl versions is an important thing. It's so
165 important that the old polluting ways of original Perl modules will not be
166 supported very far into the future, and your module will almost certainly
167 break! By adapting to it now, you'll gain compatibility and a sense of
168 having done the electronic ecology some good.
169 .Sh "How to use ppport.h"
170 .IX Subsection "How to use ppport.h"
171 Don't direct the users of your module to download \f(CW\*(C`Devel::PPPort\*(C'\fR.
172 They are most probably no \s-1XS\s0 writers. Also, don't make \fIppport.h\fR
173 optional. Rather, just take the most recent copy of \fIppport.h\fR that
174 you can find (e.g. by generating it with the latest \f(CW\*(C`Devel::PPPort\*(C'\fR
175 release from \s-1CPAN\s0), copy it into your project, adjust your project to
176 use it, and distribute the header along with your module.
177 .Sh "Running ppport.h"
178 .IX Subsection "Running ppport.h"
179 But \fIppport.h\fR is more than just a C header. It's also a Perl script
180 that can check your source code. It will suggest hints and portability
181 notes, and can even make suggestions on how to change your code. You
182 can run it like any other Perl program:
185 \& perl ppport.h [options] [files]
188 It also has embedded documentation, so you can use
194 to find out more about how to use it.
196 .IX Header "FUNCTIONS"
198 .IX Subsection "WriteFile"
199 \&\f(CW\*(C`WriteFile\*(C'\fR takes one optional argument. When called with one
200 argument, it expects to be passed a filename. When called with
201 no arguments, it defaults to the filename \fIppport.h\fR.
203 The function returns a true value if the file was written successfully.
204 Otherwise it returns a false value.
206 .IX Header "COMPATIBILITY"
207 \&\fIppport.h\fR supports Perl versions from 5.003 to 5.10.0
208 in threaded and non-threaded configurations.
209 .Sh "Provided Perl compatibility \s-1API\s0"
210 .IX Subsection "Provided Perl compatibility API"
211 The header file written by this module, typically \fIppport.h\fR, provides
212 access to the following elements of the Perl \s-1API\s0 that is not available
213 in older Perl releases:
274 \& GROK_NUMERIC_RADIX
275 \& grok_numeric_radix
287 \& IN_LOCALE_COMPILETIME
289 \& IN_PERL_COMPILETIME
291 \& IS_NUMBER_GREATER_THAN_UV_MAX
293 \& IS_NUMBER_INFINITY
354 \& PERL_GCC_BRACE_GROUPS_FORBIDDEN
361 \& PERL_MAGIC_backref
363 \& PERL_MAGIC_collxfrm
366 \& PERL_MAGIC_defelem
368 \& PERL_MAGIC_envelem
373 \& PERL_MAGIC_isaelem
376 \& PERL_MAGIC_overload
377 \& PERL_MAGIC_overload_elem
378 \& PERL_MAGIC_overload_table
381 \& PERL_MAGIC_regdata
382 \& PERL_MAGIC_regdatum
383 \& PERL_MAGIC_regex_global
385 \& PERL_MAGIC_shared_scalar
387 \& PERL_MAGIC_sigelem
392 \& PERL_MAGIC_tiedelem
393 \& PERL_MAGIC_tiedscalar
396 \& PERL_MAGIC_uvar_elem
398 \& PERL_MAGIC_vstring
399 \& PERL_PV_ESCAPE_ALL
400 \& PERL_PV_ESCAPE_FIRSTCHAR
401 \& PERL_PV_ESCAPE_NOBACKSLASH
402 \& PERL_PV_ESCAPE_NOCLEAR
403 \& PERL_PV_ESCAPE_QUOTE
405 \& PERL_PV_ESCAPE_UNI
406 \& PERL_PV_ESCAPE_UNI_DETECT
407 \& PERL_PV_PRETTY_DUMP
408 \& PERL_PV_PRETTY_ELLIPSES
409 \& PERL_PV_PRETTY_LTGT
410 \& PERL_PV_PRETTY_NOCLEAR
411 \& PERL_PV_PRETTY_QUOTE
412 \& PERL_PV_PRETTY_REGPROP
416 \& PERL_SCAN_ALLOW_UNDERSCORES
417 \& PERL_SCAN_DISALLOW_PREFIX
418 \& PERL_SCAN_GREATER_THAN_UV_MAX
419 \& PERL_SCAN_SILENT_ILLDIGIT
422 \& PERL_SIGNALS_UNSAFE_FLAG
431 \& PERL_UNUSED_CONTEXT
436 \& PERL_USE_GCC_BRACE_GROUPS
441 \& Perl_warner_nocontext
473 \& PL_perl_destruct_level
523 \& sv_catpvf_mg_nocontext
531 \& SV_COW_SHARED_HASH_KEYS
533 \& SV_HAS_TRAILING_NUL
534 \& SV_IMMEDIATE_UNREF
538 \& sv_pvn_force_flags
544 \& sv_setpvf_mg_nocontext
553 \& SV_UTF8_NO_ENCODING
568 \& SvPV_flags_const_nolen
569 \& SvPV_flags_mutable
572 \& SvPV_force_flags_mutable
573 \& SvPV_force_flags_nolen
574 \& SvPV_force_mutable
577 \& SvPV_force_nomg_nolen
583 \& SvPV_nomg_const_nolen
590 \& SvREFCNT_inc_simple
591 \& SvREFCNT_inc_simple_NN
592 \& SvREFCNT_inc_simple_void
593 \& SvREFCNT_inc_simple_void_NN
595 \& SvREFCNT_inc_void_NN
658 \& WARN_UNINITIALIZED
678 .Sh "Perl \s-1API\s0 not supported by ppport.h"
679 .IX Subsection "Perl API not supported by ppport.h"
680 There is still a big part of the \s-1API\s0 not supported by \fIppport.h\fR.
681 Either because it doesn't make sense to back-port that part of the \s-1API\s0,
682 or simply because it hasn't been implemented yet. Patches welcome!
684 Here's a list of the currently unsupported \s-1API\s0, and also the version of
685 Perl below which it is unsupported:
687 .IX Item "perl 5.11.0"
698 \& gv_fetchmethod_flags
701 \& mro_get_private_data
704 \& mro_set_private_data
710 \& save_padsv_and_mortalize
712 \& stashpv_hvname_match
714 \& sv_utf8_upgrade_flags_grow
717 .IX Item "perl 5.10.0"
727 .IX Item "perl 5.9.5"
732 \& av_create_and_push
733 \& av_create_and_unshift_one
735 \& gv_fetchfile_flags
736 \& mro_get_linear_isa
737 \& mro_method_changed_in
748 \& reg_named_buff_all
749 \& reg_named_buff_exists
750 \& reg_named_buff_fetch
751 \& reg_named_buff_firstkey
752 \& reg_named_buff_nextkey
753 \& reg_named_buff_scalar
760 .IX Item "perl 5.9.4"
762 \& PerlIO_context_layers
771 .IX Item "perl 5.9.3"
783 \& hv_placeholders_get
785 \& hv_placeholders_set
788 \& is_utf8_string_loclen
799 .IX Item "perl 5.9.2"
802 \& find_rundefsvoffset
810 .IX Item "perl 5.9.1"
812 \& hv_clear_placeholders
819 .IX Item "perl 5.9.0"
828 .IX Item "perl 5.8.3"
831 \& SvIsCOW_shared_hash
834 .IX Item "perl 5.8.1"
839 \& is_utf8_string_loc
842 \& savestack_grow_cnt
851 .IX Item "perl 5.8.0"
859 .IX Item "perl 5.7.3"
893 \& gv_fetchmeth_autoload
919 \& uvchr_to_utf8_flags
920 \& uvuni_to_utf8_flags
924 .IX Item "perl 5.7.2"
939 \& sv_utf8_upgrade_flags
940 \& sv_utf8_upgrade_nomg
944 .IX Item "perl 5.7.1"
955 \& sv_force_normal_flags
966 .IX Item "perl 5.6.1"
969 \& apply_attrs_string
974 \& save_generic_pvref
976 \& utf16_to_utf8_reversed
980 .IX Item "perl 5.6.0"
1041 \& is_uni_idfirst_lc
1094 \& save_destructor_x
1099 \& set_numeric_local
1100 \& set_numeric_radix
1101 \& set_numeric_standard
1118 \& sv_utf8_downgrade
1133 .IP "perl 5.005_03" 4
1134 .IX Item "perl 5.005_03"
1138 \& save_generic_svref
1141 .IX Item "perl 5.005"
1170 .IP "perl 5.004_05" 4
1171 .IX Item "perl 5.004_05"
1178 .IX Item "perl 5.004"
1192 \& SvSetMagicSV_nosteal
1205 \& gv_fetchmethod_autoload
1232 \& sv_magic_portable
1250 If you find any bugs, \f(CW\*(C`Devel::PPPort\*(C'\fR doesn't seem to build on your
1251 system or any of its tests fail, please use the \s-1CPAN\s0 Request Tracker
1252 at <http://rt.cpan.org/> to create a ticket for the module.
1254 .IX Header "AUTHORS"
1256 Version 1.x of Devel::PPPort was written by Kenneth Albanowski.
1258 Version 2.x was ported to the Perl core by Paul Marquess.
1260 Version 3.x was ported back to \s-1CPAN\s0 by Marcus Holland\-Moritz.
1262 .IX Header "COPYRIGHT"
1263 Version 3.x, Copyright (C) 2004\-2009, Marcus Holland\-Moritz.
1265 Version 2.x, Copyright (C) 2001, Paul Marquess.
1267 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
1269 This program is free software; you can redistribute it and/or
1270 modify it under the same terms as Perl itself.
1272 .IX Header "SEE ALSO"