X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/9a9a6c9859e31a91d4dd61190df208c24f5cbdc4..9c10ff02ede505e07dd601a89271a2e3e5e79b52:/embed.fnc

diff --git a/embed.fnc b/embed.fnc
index 1bf9e62..1f481a7 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -65,6 +65,46 @@
 : This has had to be done with things like MAX and MIN, but nearly everything
 : else has been created without regard to the namespace pollution problem.
 :
+: Here's what else you need to know about using this file with regards to name
+: space pollution:
+:
+: The A flag is used to make a function and its short name visible everywhere
+:	     on all platforms.  This should be used to make it part of Perl's
+:	     API contract with XS developers.  The documentation for these is
+:	     usually placed in perlapi.  If no documentation exists, that fact
+:	     is also noted in perlapi.
+:
+: The C flag is used instead for functions and their short names that need to
+:            be accessible everywhere, typically because they are called from a
+:            publicly available macro or inline function, but they are not for
+:            public use by themselves.  The documentation for these is placed
+:            in perlintern.  If no documentation exists, that fact is also
+:            noted in perlintern.
+:
+:            These really need the 'p' flag to avoid name space collisions.
+:
+:	     Some of these have been constructed so that the wrapper macro
+:	     names begin with an underscore to lessen the chances of a name
+:	     collision.  However, this is contrary to the C standard, and those
+:	     should be changed.
+:
+: The E flag is used instead for a function and its short name that is supposed
+:            to be used only in the core, and in extensions compiled with the
+:            PERL_EXT symbol defined.  Again, on some platforms, the function
+:            will be visible everywhere, so the 'p' flag is gnerally needed.
+:            Also note that an XS writer can always cheat and pretend to be an
+:            extension by #defining PERL_EXT.
+:
+: The X flag is similar to the C flag in that the function (whose entry better
+:	     have the 'p' flag) is accessible everywhere on all platforms.
+:	     However the short name macro that normally gets generated is
+:	     suppressed outside the core.  (Except it is also visible in
+:	     PERL_EXT extensions if the E flag is also specified.)  This flag
+:	     is used for functions that are called from a public macro, the
+:	     name of which isn't derived from the function name.  You'll have
+:	     to write the macro yourself, and from within it, refer to the
+:	     function in its full 'Perl_' form with any necessary thread
+:	     context parameter.
 :
 : Scattered around the perl source are lines of the form:
 :
@@ -249,7 +289,9 @@
 :         proto.h: function is declared as PERL_STATIC_INLINE
 :
 :   m  Implemented as a macro; there is no function associated with this name,
-:      and hence no long Perl_ or S_ name.
+:      and hence no long Perl_ or S_ name.  However, if the macro name itself
+:      begins with 'Perl_', autodoc.pl will show a thread context parameter
+:      unless the 'T' flag is specified.
 :
 :         suppress proto.h entry (actually, not suppressed, but commented out)
 :         suppress entry in the list of exported symbols available on all platforms
@@ -572,6 +614,8 @@ Apd	|void	|cv_undef	|NN CV* cv
 p	|void	|cv_undef_flags	|NN CV* cv|U32 flags
 pd	|void	|cv_forget_slab	|NULLOK CV *cv
 Ap	|void	|cx_dump	|NN PERL_CONTEXT* cx
+AiMp	|GV *	|CvGV		|NN CV *sv
+AiMTp	|I32 *	|CvDEPTH	|NN const CV * const sv
 Aphd	|SV*	|filter_add	|NULLOK filter_t funcp|NULLOK SV* datasv
 Ap	|void	|filter_del	|NN filter_t funcp
 ApRhd	|I32	|filter_read	|int idx|NN SV *buf_sv|int maxlen
@@ -1004,7 +1048,7 @@ ATidRp	|bool	|is_utf8_invariant_string_loc|NN const U8* const s	    \
 		|STRLEN len						    \
 		|NULLOK const U8 ** ep
 #ifndef EBCDIC
-CTiRp	|unsigned int|_variant_byte_number|PERL_UINTMAX_T word
+CTiRp	|unsigned int|variant_byte_number|PERL_UINTMAX_T word
 #endif
 #if defined(PERL_CORE) || defined(PERL_EXT)
 EiTRd	|Size_t	|variant_under_utf8_count|NN const U8* const s		    \
@@ -1013,7 +1057,7 @@ EiTRd	|Size_t	|variant_under_utf8_count|NN const U8* const s		    \
 AmTdRP	|bool	|is_ascii_string|NN const U8* const s|STRLEN len
 AmTdRP	|bool	|is_invariant_string|NN const U8* const s|STRLEN len
 #if defined(PERL_CORE) || defined (PERL_EXT)
-EXTidR	|bool	|is_utf8_non_invariant_string|NN const U8* const s	    \
+EXTidRp	|bool	|is_utf8_non_invariant_string|NN const U8* const s	    \
 		|STRLEN len
 #endif
 AbTpdD	|STRLEN	|is_utf8_char	|NN const U8 *s
@@ -1537,6 +1581,7 @@ ApMb	|OP*	|ref		|NULLOK OP* o|I32 type
 S	|OP*	|refkids	|NULLOK OP* o|I32 type
 #endif
 Ap	|void	|regdump	|NN const regexp* r
+CiTop	|struct regexp *|ReANY	|NN const REGEXP * const re
 #if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_PERL_C) || defined(PERL_IN_UTF8_C)
 EXpR	|SV*	|_new_invlist_C_array|NN const UV* const list
 EXp	|bool	|_invlistEQ	|NN SV* const a|NN SV* const b|const bool complement_b
@@ -1681,6 +1726,8 @@ Ap	|void	|save_pushptrptr|NULLOK void *const ptr1 \
 S	|void	|save_pushptri32ptr|NULLOK void *const ptr1|const I32 i \
 				|NULLOK void *const ptr2|const int type
 #endif
+Xiop	|I32	|TOPMARK
+Xiop	|I32	|POPMARK
 : Used in perly.y
 p	|OP*	|sawparens	|NULLOK OP* o
 Apd	|OP*	|op_contextualize|NN OP* o|I32 context
@@ -1917,15 +1964,15 @@ ESR	|SV*	|invlist_contents|NN SV* const invlist		    \
 ESRT	|bool	|new_regcurly	|NN const char *s|NN const char *e
 #endif
 #if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_UTF8_C)
-EXm	|void	|_invlist_intersection	|NN SV* const a|NN SV* const b|NN SV** i
+m	|void	|_invlist_intersection	|NN SV* const a|NN SV* const b|NN SV** i
 EXp	|void	|_invlist_intersection_maybe_complement_2nd \
 		|NULLOK SV* const a|NN SV* const b          \
 		|const bool complement_b|NN SV** i
-EXm	|void	|_invlist_union	|NULLOK SV* const a|NN SV* const b|NN SV** output
+Cm	|void	|_invlist_union	|NULLOK SV* const a|NN SV* const b|NN SV** output
 EXp	|void	|_invlist_union_maybe_complement_2nd        \
 		|NULLOK SV* const a|NN SV* const b          \
 		|const bool complement_b|NN SV** output
-EXm	|void	|_invlist_subtract|NN SV* const a|NN SV* const b|NN SV** result
+m	|void	|_invlist_subtract|NN SV* const a|NN SV* const b|NN SV** result
 EXp	|void	|_invlist_invert|NN SV* const invlist
 EXpR	|SV*	|_new_invlist	|IV initial_size
 EXpR	|SV*	|_add_range_to_invlist	|NULLOK SV* invlist|UV start|UV end
@@ -1942,6 +1989,9 @@ EiRT	|UV	|_invlist_len	|NN SV* const invlist
 EiRT	|bool	|_invlist_contains_cp|NN SV* const invlist|const UV cp
 EXpRT	|SSize_t|_invlist_search	|NN SV* const invlist|const UV cp
 #endif
+#if defined(PERL_IN_PP_C) || defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_TOKE_C) || defined(PERL_IN_UNIVERSAL_C)
+EiT	|const char *|get_regex_charset_name|const U32 flags|NN STRLEN* const lenp
+#endif
 #if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_REGEXEC_C)
 EXp	|SV*	|_get_regclass_nonbitmap_data				   \
 				|NULLOK const regexp *prog		   \
@@ -2251,6 +2301,13 @@ pX	|SSize_t|tmps_grow_p	|SSize_t ix
 Apd	|SV*	|sv_rvweaken	|NN SV *const sv
 Apd	|SV*	|sv_rvunweaken	|NN SV *const sv
 ATpxd	|SV*	|sv_get_backrefs|NN SV *const sv
+AiTMdp	|SV *	|SvREFCNT_inc	|NULLOK SV *sv
+AiTMdp	|SV *	|SvREFCNT_inc_NN|NN SV *sv
+AiTMdp	|void	|SvREFCNT_inc_void|NULLOK SV *sv
+AiMdp	|void	|SvREFCNT_dec	|NULLOK SV *sv
+AiMdp	|void	|SvREFCNT_dec_NN|NN SV *sv
+AiTp	|void	|SvAMAGIC_on	|NN SV *sv
+AiTp	|void	|SvAMAGIC_off	|NN SV *sv
 : This is indirectly referenced by globals.c. This is somewhat annoying.
 p	|int	|magic_killbackrefs|NN SV *sv|NN MAGIC *mg
 Ap	|OP*	|newANONATTRSUB	|I32 floor|NULLOK OP *proto|NULLOK OP *attrs|NULLOK OP *block
@@ -2303,7 +2360,9 @@ Ap	|void	|sys_intern_dup	|NN struct interp_intern* src|NN struct interp_intern*
 #  endif
 #endif
 
-Admop	|const XOP *	|custom_op_xop	|NN const OP *o
+: The reason for the 'u' flag is that this passes "aTHX_ x" to its callee: not
+: a legal C parameter
+Admu	|const XOP *	|Perl_custom_op_xop	|NN const OP *o
 AbpRdD	|const char *	|custom_op_name	|NN const OP *o
 AbpRdD	|const char *	|custom_op_desc	|NN const OP *o
 pRX	|XOPRETANY	|custom_op_get_field	|NN const OP *o|const xop_flags_enum field
@@ -3234,6 +3293,9 @@ pd	|void	|do_dump_pad	|I32 level|NN PerlIO *file|NULLOK PADLIST *padlist|int ful
 Sd	|void	|cv_dump	|NN const CV *cv|NN const char *title
 #  endif
 #endif
+#if defined(PERL_IN_PAD_C) || defined(PERL_IN_OP_C)
+iT	|bool	|PadnameIN_SCOPE|NN const PADNAME * const pn|const U32 seq
+#endif
 Apd	|CV*	|cv_clone	|NN CV* proto
 p	|CV*	|cv_clone_into	|NN CV* proto|NN CV *target
 pd	|void	|pad_fixup_inner_anons|NN PADLIST *padlist|NN CV *old_cv|NN CV *new_cv