This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify that patching deprecate.pm is intended to facilitate a staged transition.
[perl5.git] / embed.fnc
index 6b24d1e..f93d27c 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -1,5 +1,7 @@
 : BEGIN {die "You meant to run embed.pl"} # Stop early if fed to perl.
 :
+: This file is processed by embed.pl and autodoc.pl
+:
 : Lines are of the form:
 :    flags|return_type|function_name|arg1|arg2|...|argN
 :
 : Leading and trailing whitespace will be ignored in each component.
 :
 : flags are single letters with following meanings:
-:      A               member of public API
-:      m               Implemented as a macro - no export, no
-:                      proto, no #define
-:      d               function has documentation with its source
-:      D               function is deprecated
-:      s               static function, should have an S_ prefix in
-:                      source file; for macros (m), suffix the usage
-:                      example with a semicolon
-:      n               has no implicit interpreter/thread context argument
-:      p               function has a Perl_ prefix
-:      f               function takes printf style format string, varargs
-:      r               function never returns
-:      o               has no compatibility macro (#define foo Perl_foo)
-:      x               not exported
-:      X               explicitly exported
-:      M               may change
-:      E               visible to extensions included in the Perl core
-:      b               binary backward compatibility; function is a macro
-:                      but has also Perl_ implementation (which is exported)
-:      U               suppress usage example in autogenerated documentation
-:      a               allocates memory a la malloc/calloc.  Is also "R".
-:      R               Return value must not be ignored.
-:      P               pure function: no effects except the return value;
-:                      return value depends only on parms and/or globals
+:
+:   A  Member of public API:
+:
+:         add entry to global.sym (unless x or m);
+:         any doc entry goes in perlapi.pod rather than perlintern.api
+:         makes '#define foo Perl_foo' scope not just for PERL_CORE/PERL_EXT
+:
+:   a  Allocates memory a la malloc/calloc.  Also implies "R":
+:
+:         proto.h: add __attribute__malloc__
+:
+:   b  Binary backward compatibility; function is a macro
+:      but has also Perl_ implementation (which is exported):
+:
+:         add entry to global.sym;
+:         don't define PERL_ARGS_ASSERT_FOO
+:
+:   D  Function is deprecated:
+:
+:         proto.h: add __attribute__deprecated__
+:
+:   d  Function has documentation with its source:
+:
+:         enables 'no docs for foo" warning in autodoc.pl
+:
+:   E  Visible to extensions included in the Perl core:
+:
+:         in embed.h, change "#ifdef PERL_CORE"
+:         into               "#if defined(PERL_CORE) || defined(PERL_EXT)"
+:
+:      Should always be combined with "X" to be usable from dynamically
+:      loaded extensions.
+:
+:   f  Function takes printf style format string, varargs:
+:
+:         proto.h: add __attribute__format__ (or ...null_ok__)
+:
+:   M  May change:
+:
+:         (currently no effect)
+:
+:   m  Implemented as a macro:
+:
+:         suppress proto.h entry
+:         suppress global.sym entry
+:         suppress embed.h entry
+:
+:   n  Has no implicit interpreter/thread context argument:
+:
+:         suppress the pTHX part of "foo(pTHX...)" in proto.h;
+:         In the PERL_IMPLICIT_SYS branch of embed.h, generates
+:             "#define foo Perl_foo",      rather than
+:             "#define foo(a,b,c) Perl_foo(aTHX_ a,b,c)
+:
+:   o  Has no Perl_foo compatibility macro:
+:
+:         embed.h: suppress "#define foo Perl_foo"
+:
+:   P  Pure function: no effects except the return value;
+:      return value depends only on params and/or globals:
+:
+:         proto.h: add __attribute__pure__
+:
+:   p  Function in source code has a Perl_ prefix:
+:
+:         proto.h: function is declared as Perl_foo rather than foo
+:         embed.h: "#define foo Perl_foo" entries added
+:
+:   R  Return value must not be ignored (also implied by 'a' flag):
+:
+:        proto.h: add __attribute__warn_unused_result__
+:
+:   r  Function never returns:
+:
+:        proto.h: add __attribute__noreturn__
+:
+:   s  Static function: function in source code has a S_ prefix:
+:
+:         proto.h: function is declared as S_foo rather than foo,
+:                STATIC is added to declaration;
+:         embed.h: "#define foo S_foo" entries added
+:
+:   U  Suppress usage example in autogenerated documentation
+:
+:         (currently no effect)
+:
+:   X  Explicitly exported:
+:
+:         add entry to global.sym, unless x or m
+:
+:   x  Not exported
+:
+:         suppress entry in global.sym
+:
 : (see also L<perlguts/Internal Functions> for those flags.)
 :
 : Pointer parameters that must not be passed NULLs should be prefixed with NN.
@@ -93,6 +165,7 @@ npR  |MEM_SIZE|malloc_good_size      |size_t nbytes
 
 AnpR   |void*  |get_context
 Anp    |void   |set_context    |NN void *t
+EXpRnP |I32    |regcurly       |NN const char *s
 
 END_EXTERN_C
 
@@ -365,7 +438,7 @@ Ap  |void   |gv_fullname4   |NN SV* sv|NN const GV* gv|NULLOK const char* prefix|bool
 pMox   |GP *   |newGP          |NN GV *const gv
 Ap     |void   |gv_init        |NN GV* gv|NULLOK HV* stash|NN const char* name|STRLEN len|int multi
 Ap     |void   |gv_name_set    |NN GV* gv|NN const char *name|U32 len|U32 flags
-Apd    |void   |gv_try_downgrade|NN GV* gv
+XMpd   |void   |gv_try_downgrade|NN GV* gv
 Apd    |HV*    |gv_stashpv     |NN const char* name|I32 flags
 Apd    |HV*    |gv_stashpvn    |NN const char* name|U32 namelen|I32 flags
 Apd    |HV*    |gv_stashsv     |NN SV* sv|I32 flags
@@ -502,16 +575,16 @@ ApR       |bool   |is_utf8_print  |NN const U8 *p
 ApR    |bool   |is_utf8_punct  |NN const U8 *p
 ApR    |bool   |is_utf8_xdigit |NN const U8 *p
 ApR    |bool   |is_utf8_mark   |NN const U8 *p
-pR     |bool   |is_utf8_X_begin        |NN const U8 *p
-pR     |bool   |is_utf8_X_extend       |NN const U8 *p
-pR     |bool   |is_utf8_X_prepend      |NN const U8 *p
-pR     |bool   |is_utf8_X_non_hangul   |NN const U8 *p
-pR     |bool   |is_utf8_X_L            |NN const U8 *p
-pR     |bool   |is_utf8_X_LV           |NN const U8 *p
-pR     |bool   |is_utf8_X_LVT          |NN const U8 *p
-pR     |bool   |is_utf8_X_LV_LVT_V     |NN const U8 *p
-pR     |bool   |is_utf8_X_T            |NN const U8 *p
-pR     |bool   |is_utf8_X_V            |NN const U8 *p
+EXpR   |bool   |is_utf8_X_begin        |NN const U8 *p
+EXpR   |bool   |is_utf8_X_extend       |NN const U8 *p
+EXpR   |bool   |is_utf8_X_prepend      |NN const U8 *p
+EXpR   |bool   |is_utf8_X_non_hangul   |NN const U8 *p
+EXpR   |bool   |is_utf8_X_L            |NN const U8 *p
+EXpR   |bool   |is_utf8_X_LV           |NN const U8 *p
+EXpR   |bool   |is_utf8_X_LVT          |NN const U8 *p
+EXpR   |bool   |is_utf8_X_LV_LVT_V     |NN const U8 *p
+EXpR   |bool   |is_utf8_X_T            |NN const U8 *p
+EXpR   |bool   |is_utf8_X_V            |NN const U8 *p
 : Used in perly.y
 p      |OP*    |jmaybe         |NN OP *o
 : Used in pp.c 
@@ -745,6 +818,9 @@ Apa |PERL_SI*|new_stackinfo|I32 stitems|I32 cxitems
 Ap     |char*  |scan_vstring   |NN const char *s|NN const char *const e \
                                |NN SV *sv
 Apd    |const char*    |scan_version   |NN const char *s|NN SV *rv|bool qv
+Apd    |const char*    |prescan_version        |NN const char *s\
+       |bool strict|NULLOK const char** errstr|NULLOK bool *sqv\
+       |NULLOK int *ssaw_decimal|NULLOK int *swidth|NULLOK bool *salpha
 Apd    |SV*    |new_version    |NN SV *ver
 Apd    |SV*    |upg_version    |NN SV *ver|bool qv
 Apd    |bool   |vverify        |NN SV *vs
@@ -1090,6 +1166,8 @@ ApdR      |SV*    |sv_newmortal
 Apd    |SV*    |sv_newref      |NULLOK SV *const sv
 Ap     |char*  |sv_peek        |NULLOK SV* sv
 Apd    |void   |sv_pos_u2b     |NULLOK SV *const sv|NN I32 *const offsetp|NULLOK I32 *const lenp
+Apd    |STRLEN |sv_pos_u2b_flags|NN SV *const sv|STRLEN uoffset \
+                               |NULLOK STRLEN *const lenp|U32 flags
 Apd    |void   |sv_pos_b2u     |NULLOK SV *const sv|NN I32 *const offsetp
 Amdb   |char*  |sv_pvn_force   |NN SV* sv|NULLOK STRLEN* lp
 Apd    |char*  |sv_pvutf8n_force|NN SV *const sv|NULLOK STRLEN *const lp
@@ -1629,7 +1707,6 @@ Es        |regnode*|regbranch     |NN struct RExC_state_t *pRExC_state \
 Es     |STRLEN |reguni         |NN const struct RExC_state_t *pRExC_state \
                                |UV uv|NN char *s
 Es     |regnode*|regclass      |NN struct RExC_state_t *pRExC_state|U32 depth
-ERsn   |I32    |regcurly       |NN const char *s
 Es     |regnode*|reg_node      |NN struct RExC_state_t *pRExC_state|U8 op
 Es     |UV     |reg_recode     |const char value|NN SV **encp
 Es     |regnode*|regpiece      |NN struct RExC_state_t *pRExC_state \
@@ -1804,6 +1881,7 @@ sRn       |PTR_TBL_ENT_t *|ptr_table_find|NN PTR_TBL_t *const tbl|NULLOK const void *c
 s      |void   |check_uni
 s      |void   |force_next     |I32 type
 s      |char*  |force_version  |NN char *s|int guessing
+s      |char*  |force_strict_version   |NN char *s
 s      |char*  |force_word     |NN char *start|int token|int check_keyword \
                                |int allow_pack|int allow_tick
 s      |SV*    |tokeq          |NN SV *sv