1Devel::PPPort(3pm) Perl Programmers Reference Guide Devel::PPPort(3pm)
2
6 Devel::PPPort - Perl/Pollution/Portability
7
9 Devel::PPPort::WriteFile(); # defaults to ./ppport.h
10 Devel::PPPort::WriteFile('someheader.h');
11
13 Perl's API has changed over time, gaining new features, new functions,
14 increasing its flexibility, and reducing the impact on the C namespace
15 environment (reduced pollution). The header file written by this mod‐
16 ule, typically ppport.h, attempts to bring some of the newer Perl API
17 features to older versions of Perl, so that you can worry less about
18 keeping track of old releases, but users can still reap the benefit.
19 "Devel::PPPort" contains a single function, called "WriteFile". Its
21 only purpose is to write the ppport.h C header file. This file contains
22 a series of macros and, if explicitly requested, functions that allow
23 XS modules to be built using older versions of Perl. Currently, Perl
24 versions from 5.003 to 5.9.3 are supported.
25 This module is used by "h2xs" to write the file ppport.h.
27 Why use ppport.h?
29 You should use ppport.h in modern code so that your code will work with
31 the widest range of Perl interpreters possible, without significant
32 additional work.
33 You should attempt older code to fully use ppport.h, because the
35 reduced pollution of newer Perl versions is an important thing. It's so
36 important that the old polluting ways of original Perl modules will not
37 be supported very far into the future, and your module will almost cer‐
38 tainly break! By adapting to it now, you'll gain compatibility and a
39 sense of having done the electronic ecology some good.
40 How to use ppport.h
42 Don't direct the users of your module to download "Devel::PPPort".
44 They are most probably no XS writers. Also, don't make ppport.h
45 optional. Rather, just take the most recent copy of ppport.h that you
46 can find (e.g. by generating it with the latest "Devel::PPPort" release
47 from CPAN), copy it into your project, adjust your project to use it,
48 and distribute the header along with your module.
49 Running ppport.h
51 But ppport.h is more than just a C header. It's also a Perl script that
53 can check your source code. It will suggest hints and portability
54 notes, and can even make suggestions on how to change your code. You
55 can run it like any other Perl program:
56 perl ppport.h [options] [files]
58 It also has embedded documentation, so you can use
60 perldoc ppport.h
62 to find out more about how to use it.
64
66 WriteFile
67 "WriteFile" takes one optional argument. When called with one argument,
69 it expects to be passed a filename. When called with no arguments, it
70 defaults to the filename ppport.h.
71 The function returns a true value if the file was written successfully.
73 Otherwise it returns a false value.
74
76 ppport.h supports Perl versions from 5.003 to 5.9.3 in threaded and
77 non-threaded configurations.
78 Provided Perl compatibility API
80 The header file written by this module, typically ppport.h, provides
82 access to the following elements of the Perl API that is not available
83 in older Perl releases:
84 _aMY_CXT
86 _pMY_CXT
87 aMY_CXT
88 aMY_CXT_
89 aTHX
90 aTHX_
91 AvFILLp
92 boolSV
93 call_argv
94 call_method
95 call_pv
96 call_sv
97 CopFILE
98 CopFILE_set
99 CopFILEAV
100 CopFILEGV
101 CopFILEGV_set
102 CopFILESV
103 CopSTASH
104 CopSTASH_eq
105 CopSTASH_set
106 CopSTASHPV
107 CopSTASHPV_set
108 CopyD
109 dAX
110 DEFSV
111 dITEMS
112 dMY_CXT
113 dMY_CXT_SV
114 dNOOP
115 dTHR
116 dTHX
117 dTHXa
118 dTHXoa
119 dUNDERBAR
120 dXCPT
121 dXSTARG
122 END_EXTERN_C
123 ERRSV
124 eval_pv
125 eval_sv
126 EXTERN_C
127 get_av
128 get_cv
129 get_hv
130 get_sv
131 grok_bin
132 grok_hex
133 grok_number
134 GROK_NUMERIC_RADIX
135 grok_numeric_radix
136 grok_oct
137 gv_stashpvn
138 IN_LOCALE
139 IN_LOCALE_COMPILETIME
140 IN_LOCALE_RUNTIME
141 IN_PERL_COMPILETIME
142 INT2PTR
143 IS_NUMBER_GREATER_THAN_UV_MAX
144 IS_NUMBER_IN_UV
145 IS_NUMBER_INFINITY
146 IS_NUMBER_NAN
147 IS_NUMBER_NEG
148 IS_NUMBER_NOT_INT
149 IVdf
150 IVSIZE
151 IVTYPE
152 memEQ
153 memNE
154 MoveD
155 mPUSHi
156 mPUSHn
157 mPUSHp
158 mPUSHu
159 mXPUSHi
160 mXPUSHn
161 mXPUSHp
162 mXPUSHu
163 MY_CXT
164 MY_CXT_CLONE
165 MY_CXT_INIT
166 newCONSTSUB
167 newRV_inc
168 newRV_noinc
169 newSVpvn
170 newSVuv
171 NOOP
172 NUM2PTR
173 NVef
174 NVff
175 NVgf
176 NVTYPE
177 PERL_BCDVERSION
178 PERL_GCC_BRACE_GROUPS_FORBIDDEN
179 PERL_INT_MAX
180 PERL_INT_MIN
181 PERL_LONG_MAX
182 PERL_LONG_MIN
183 PERL_MAGIC_arylen
184 PERL_MAGIC_backref
185 PERL_MAGIC_bm
186 PERL_MAGIC_collxfrm
187 PERL_MAGIC_dbfile
188 PERL_MAGIC_dbline
189 PERL_MAGIC_defelem
190 PERL_MAGIC_env
191 PERL_MAGIC_envelem
192 PERL_MAGIC_ext
193 PERL_MAGIC_fm
194 PERL_MAGIC_glob
195 PERL_MAGIC_isa
196 PERL_MAGIC_isaelem
197 PERL_MAGIC_mutex
198 PERL_MAGIC_nkeys
199 PERL_MAGIC_overload
200 PERL_MAGIC_overload_elem
201 PERL_MAGIC_overload_table
202 PERL_MAGIC_pos
203 PERL_MAGIC_qr
204 PERL_MAGIC_regdata
205 PERL_MAGIC_regdatum
206 PERL_MAGIC_regex_global
207 PERL_MAGIC_shared
208 PERL_MAGIC_shared_scalar
209 PERL_MAGIC_sig
210 PERL_MAGIC_sigelem
211 PERL_MAGIC_substr
212 PERL_MAGIC_sv
213 PERL_MAGIC_taint
214 PERL_MAGIC_tied
215 PERL_MAGIC_tiedelem
216 PERL_MAGIC_tiedscalar
217 PERL_MAGIC_utf8
218 PERL_MAGIC_uvar
219 PERL_MAGIC_uvar_elem
220 PERL_MAGIC_vec
221 PERL_MAGIC_vstring
222 PERL_QUAD_MAX
223 PERL_QUAD_MIN
224 PERL_REVISION
225 PERL_SCAN_ALLOW_UNDERSCORES
226 PERL_SCAN_DISALLOW_PREFIX
227 PERL_SCAN_GREATER_THAN_UV_MAX
228 PERL_SCAN_SILENT_ILLDIGIT
229 PERL_SHORT_MAX
230 PERL_SHORT_MIN
231 PERL_SUBVERSION
232 PERL_UCHAR_MAX
233 PERL_UCHAR_MIN
234 PERL_UINT_MAX
235 PERL_UINT_MIN
236 PERL_ULONG_MAX
237 PERL_ULONG_MIN
238 PERL_UNUSED_DECL
239 PERL_UQUAD_MAX
240 PERL_UQUAD_MIN
241 PERL_USHORT_MAX
242 PERL_USHORT_MIN
243 PERL_VERSION
244 PL_compiling
245 PL_copline
246 PL_curcop
247 PL_curstash
248 PL_DBsingle
249 PL_DBsub
250 PL_debstash
251 PL_defgv
252 PL_diehook
253 PL_dirty
254 PL_dowarn
255 PL_errgv
256 PL_hexdigit
257 PL_hints
258 PL_na
259 PL_no_modify
260 PL_perl_destruct_level
261 PL_perldb
262 PL_ppaddr
263 PL_rsfp
264 PL_rsfp_filters
265 PL_stack_base
266 PL_stack_sp
267 PL_stdingv
268 PL_Sv
269 PL_sv_arenaroot
270 PL_sv_no
271 PL_sv_undef
272 PL_sv_yes
273 PL_tainted
274 PL_tainting
275 pMY_CXT
276 pMY_CXT_
277 Poison
278 pTHX
279 pTHX_
280 PTR2IV
281 PTR2NV
282 PTR2ul
283 PTR2UV
284 PTRV
285 PUSHmortal
286 PUSHu
287 SAVE_DEFSV
288 START_EXTERN_C
289 START_MY_CXT
290 STMT_END
291 STMT_START
292 sv_2pv_nolen
293 sv_2pvbyte
294 sv_2uv
295 sv_catpv_mg
296 sv_catpvf_mg
297 sv_catpvf_mg_nocontext
298 sv_catpvn_mg
299 sv_catpvn_nomg
300 sv_catsv_mg
301 sv_catsv_nomg
302 sv_pvn
303 sv_pvn_force
304 sv_pvn_nomg
305 sv_setiv_mg
306 sv_setnv_mg
307 sv_setpv_mg
308 sv_setpvf_mg
309 sv_setpvf_mg_nocontext
310 sv_setpvn_mg
311 sv_setsv_mg
312 sv_setsv_nomg
313 sv_setuv
314 sv_setuv_mg
315 sv_usepvn_mg
316 sv_uv
317 sv_vcatpvf
318 sv_vcatpvf_mg
319 sv_vsetpvf
320 sv_vsetpvf_mg
321 SvGETMAGIC
322 SvIV_nomg
323 SvPV_force_nomg
324 SvPV_nolen
325 SvPV_nomg
326 SvPVbyte
327 SvUV
328 SvUV_nomg
329 SvUVX
330 SvUVx
331 SvUVXx
332 UNDERBAR
333 UVof
334 UVSIZE
335 UVTYPE
336 UVuf
337 UVXf
338 UVxf
339 vnewSVpvf
340 XCPT_CATCH
341 XCPT_RETHROW
342 XCPT_TRY_END
343 XCPT_TRY_START
344 XPUSHmortal
345 XPUSHu
346 XSRETURN_UV
347 XST_mUV
348 ZeroD
349 Perl API not supported by ppport.h
351 There is still a big part of the API not supported by ppport.h. Either
353 because it doesn't make sense to back-port that part of the API, or
354 simply because it hasn't been implemented yet. Patches welcome!
355 Here's a list of the currently unsupported API, and also the version of
357 Perl below which it is unsupported:
358 perl 5.9.3
360 SvMAGIC_set
361 SvRV_set
362 SvSTASH_set
363 SvUV_set
364 av_arylen_p
365 dAXMARK
366 hv_eiter_p
367 hv_eiter_set
368 hv_name_set
369 hv_placeholders_get
370 hv_placeholders_p
371 hv_placeholders_set
372 hv_riter_p
373 hv_riter_set
374 is_utf8_string_loclen
375 newSVhek
376 newWHILEOP
377 stashpv_hvname_match
378 perl 5.9.2
380 SvPVbyte_force
381 find_rundefsvoffset
382 gv_fetchpvn_flags
383 gv_fetchsv
384 op_refcnt_lock
385 op_refcnt_unlock
386 savesvpv
387 vnormal
388 perl 5.9.1
390 hv_assert
391 hv_clear_placeholders
392 hv_scalar
393 scan_version
394 sv_2iv_flags
395 sv_2uv_flags
396 perl 5.9.0
398 new_version
399 save_set_svflags
400 upg_version
401 vcmp
402 vnumify
403 vstringify
404 perl 5.8.3
406 SvIsCOW
407 SvIsCOW_shared_hash
408 perl 5.8.1
410 SvVOK
411 doing_taint
412 is_utf8_string_loc
413 packlist
414 save_bool
415 savestack_grow_cnt
416 scan_vstring
417 sv_cat_decode
418 sv_compile_2op
419 sv_setpviv
420 sv_setpviv_mg
421 unpackstring
422 perl 5.8.0
424 hv_iternext_flags
425 hv_store_flags
426 is_utf8_idcont
427 nothreadhook
428 perl 5.7.3
430 PerlIO_clearerr
431 PerlIO_close
432 PerlIO_eof
433 PerlIO_error
434 PerlIO_fileno
435 PerlIO_fill
436 PerlIO_flush
437 PerlIO_get_base
438 PerlIO_get_bufsiz
439 PerlIO_get_cnt
440 PerlIO_get_ptr
441 PerlIO_read
442 PerlIO_seek
443 PerlIO_set_cnt
444 PerlIO_set_ptrcnt
445 PerlIO_setlinebuf
446 PerlIO_stderr
447 PerlIO_stdin
448 PerlIO_stdout
449 PerlIO_tell
450 PerlIO_unread
451 PerlIO_write
452 SvLOCK
453 SvSHARE
454 SvUNLOCK
455 atfork_lock
456 atfork_unlock
457 custom_op_desc
458 custom_op_name
459 deb
460 debstack
461 debstackptrs
462 gv_fetchmeth_autoload
463 ibcmp_utf8
464 my_fork
465 my_socketpair
466 pack_cat
467 perl_destruct
468 pv_uni_display
469 regclass_swash
470 save_shared_pvref
471 savesharedpv
472 sortsv
473 sv_copypv
474 sv_magicext
475 sv_nolocking
476 sv_nosharing
477 sv_nounlocking
478 sv_recode_to_utf8
479 sv_uni_display
480 to_uni_fold
481 to_uni_lower
482 to_uni_title
483 to_uni_upper
484 to_utf8_case
485 to_utf8_fold
486 to_utf8_lower
487 to_utf8_title
488 to_utf8_upper
489 unpack_str
490 uvchr_to_utf8_flags
491 uvuni_to_utf8_flags
492 vdeb
493 perl 5.7.2
495 calloc
496 getcwd_sv
497 init_tm
498 malloc
499 mfree
500 mini_mktime
501 my_atof2
502 my_strftime
503 op_null
504 realloc
505 sv_2pv_flags
506 sv_catpvn_flags
507 sv_catsv_flags
508 sv_pvn_force_flags
509 sv_setsv_flags
510 sv_utf8_upgrade_flags
511 swash_fetch
512 perl 5.7.1
514 POPpbytex
515 SvUOK
516 bytes_from_utf8
517 csighandler
518 despatch_signals
519 do_openn
520 gv_handler
521 is_lvalue_sub
522 my_popen_list
523 newSVpvn_share
524 save_mortalizesv
525 save_padsv
526 scan_num
527 sv_force_normal_flags
528 sv_setref_uv
529 sv_unref_flags
530 sv_utf8_upgrade
531 utf8_length
532 utf8_to_uvchr
533 utf8_to_uvuni
534 utf8n_to_uvchr
535 utf8n_to_uvuni
536 uvchr_to_utf8
537 uvuni_to_utf8
538 perl 5.6.1
540 apply_attrs_string
541 bytes_to_utf8
542 gv_efullname4
543 gv_fullname4
544 is_utf8_string
545 save_generic_pvref
546 utf16_to_utf8
547 utf16_to_utf8_reversed
548 utf8_to_bytes
549 perl 5.6.0
551 SvIOK_UV
552 SvIOK_notUV
553 SvIOK_only_UV
554 SvPOK_only_UTF8
555 SvPVbyte_nolen
556 SvPVbytex
557 SvPVbytex_force
558 SvPVutf8
559 SvPVutf8_force
560 SvPVutf8_nolen
561 SvPVutf8x
562 SvPVutf8x_force
563 SvUTF8
564 SvUTF8_off
565 SvUTF8_on
566 av_delete
567 av_exists
568 call_atexit
569 cast_i32
570 cast_iv
571 cast_ulong
572 cast_uv
573 do_gv_dump
574 do_gvgv_dump
575 do_hv_dump
576 do_magic_dump
577 do_op_dump
578 do_open9
579 do_pmop_dump
580 do_sv_dump
581 dump_all
582 dump_eval
583 dump_form
584 dump_indent
585 dump_packsubs
586 dump_sub
587 dump_vindent
588 get_context
589 get_ppaddr
590 gv_dump
591 init_i18nl10n
592 init_i18nl14n
593 is_uni_alnum
594 is_uni_alnum_lc
595 is_uni_alnumc
596 is_uni_alnumc_lc
597 is_uni_alpha
598 is_uni_alpha_lc
599 is_uni_ascii
600 is_uni_ascii_lc
601 is_uni_cntrl
602 is_uni_cntrl_lc
603 is_uni_digit
604 is_uni_digit_lc
605 is_uni_graph
606 is_uni_graph_lc
607 is_uni_idfirst
608 is_uni_idfirst_lc
609 is_uni_lower
610 is_uni_lower_lc
611 is_uni_print
612 is_uni_print_lc
613 is_uni_punct
614 is_uni_punct_lc
615 is_uni_space
616 is_uni_space_lc
617 is_uni_upper
618 is_uni_upper_lc
619 is_uni_xdigit
620 is_uni_xdigit_lc
621 is_utf8_alnum
622 is_utf8_alnumc
623 is_utf8_alpha
624 is_utf8_ascii
625 is_utf8_char
626 is_utf8_cntrl
627 is_utf8_digit
628 is_utf8_graph
629 is_utf8_idfirst
630 is_utf8_lower
631 is_utf8_mark
632 is_utf8_print
633 is_utf8_punct
634 is_utf8_space
635 is_utf8_upper
636 is_utf8_xdigit
637 load_module
638 magic_dump
639 mess
640 my_atof
641 my_fflush_all
642 newANONATTRSUB
643 newATTRSUB
644 newMYSUB
645 newPADOP
646 newXS
647 newXSproto
648 new_collate
649 new_ctype
650 new_numeric
651 op_dump
652 perl_parse
653 pmop_dump
654 pv_display
655 re_intuit_start
656 re_intuit_string
657 reginitcolors
658 require_pv
659 safesyscalloc
660 safesysfree
661 safesysmalloc
662 safesysrealloc
663 save_I8
664 save_alloc
665 save_destructor
666 save_destructor_x
667 save_re_context
668 save_vptr
669 scan_bin
670 set_context
671 set_numeric_local
672 set_numeric_radix
673 set_numeric_standard
674 str_to_version
675 sv_2pvutf8
676 sv_2pvutf8_nolen
677 sv_force_normal
678 sv_len_utf8
679 sv_pos_b2u
680 sv_pos_u2b
681 sv_pv
682 sv_pvbyte
683 sv_pvbyten
684 sv_pvbyten_force
685 sv_pvutf8
686 sv_pvutf8n
687 sv_pvutf8n_force
688 sv_rvweaken
689 sv_utf8_decode
690 sv_utf8_downgrade
691 sv_utf8_encode
692 swash_init
693 tmps_grow
694 to_uni_lower_lc
695 to_uni_title_lc
696 to_uni_upper_lc
697 utf8_distance
698 utf8_hop
699 vcroak
700 vform
701 vload_module
702 vmess
703 vwarn
704 vwarner
705 warner
706 perl 5.005_03
708 POPpx
709 get_vtbl
710 save_generic_svref
711 perl 5.005
713 PL_modglobal
714 cx_dump
715 debop
716 debprofdump
717 fbm_compile
718 fbm_instr
719 get_op_descs
720 get_op_names
721 init_stacks
722 mg_length
723 mg_size
724 newHVhv
725 new_stackinfo
726 regdump
727 regexec_flags
728 regnext
729 runops_debug
730 runops_standard
731 save_hints
732 save_iv
733 save_threadsv
734 screaminstr
735 sv_iv
736 sv_nv
737 sv_peek
738 sv_true
739 perl 5.004_05
741 do_binmode
742 save_aelem
743 save_helem
744 perl 5.004
746 GIMME_V
747 G_VOID
748 HEf_SVKEY
749 HeHASH
750 HeKEY
751 HeKLEN
752 HePV
753 HeSVKEY
754 HeSVKEY_force
755 HeSVKEY_set
756 HeVAL
757 SvSetMagicSV
758 SvSetMagicSV_nosteal
759 SvSetSV_nosteal
760 SvTAINTED
761 SvTAINTED_off
762 SvTAINTED_on
763 block_gimme
764 call_list
765 cv_const_sv
766 delimcpy
767 do_open
768 form
769 gv_autoload4
770 gv_efullname3
771 gv_fetchmethod_autoload
772 gv_fullname3
773 hv_delayfree_ent
774 hv_delete_ent
775 hv_exists_ent
776 hv_fetch_ent
777 hv_free_ent
778 hv_iterkeysv
779 hv_ksplit
780 hv_store_ent
781 ibcmp_locale
782 my_failure_exit
783 my_memcmp
784 my_pclose
785 my_popen
786 newSVpvf
787 rsignal
788 rsignal_state
789 save_I16
790 save_gp
791 start_subparse
792 sv_catpvf
793 sv_catpvf_mg
794 sv_cmp_locale
795 sv_derived_from
796 sv_gets
797 sv_setpvf
798 sv_setpvf_mg
799 sv_taint
800 sv_tainted
801 sv_untaint
802 sv_vcatpvf
803 sv_vcatpvf_mg
804 sv_vcatpvfn
805 sv_vsetpvf
806 sv_vsetpvf_mg
807 sv_vsetpvfn
808 unsharepvn
809 vnewSVpvf
810
812 If you find any bugs, "Devel::PPPort" doesn't seem to build on your
813 system or any of its tests fail, please use the CPAN Request Tracker at
814 <http://rt.cpan.org/> to create a ticket for the module.
815
817 · Version 1.x of Devel::PPPort was written by Kenneth Albanowski.
818 · Version 2.x was ported to the Perl core by Paul Marquess.
820 · Version 3.x was ported back to CPAN by Marcus Holland-Moritz.
822
824 Version 3.x, Copyright (C) 2004-2005, Marcus Holland-Moritz.
825 Version 2.x, Copyright (C) 2001, Paul Marquess.
827 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
829 This program is free software; you can redistribute it and/or modify it
831 under the same terms as Perl itself.
832
834 See h2xs, ppport.h.
835perl v5.8.8 2001-09-21 Devel::PPPort(3pm)