X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/e4aeb12f0611f53a3b2e82d7d97bc9ab2a094b55..a2c6bb3c2ea3dd75c5b5617ba65ba208f7ff1079:/embed.fnc diff --git a/embed.fnc b/embed.fnc index 47d9587..b8d429a 100644 --- a/embed.fnc +++ b/embed.fnc @@ -1,16 +1,26 @@ : BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl. : -: This file is processed by regen/embed.pl and autodoc.pl -: It is used to declare the interfaces to the functions defined by perl. All -: non-static functions must have entries here. Static functions need not, but -: there is benefit to declaring them here, as it generally handles the thread -: context parameter invisibly, as well as making sure a PERL_ARGS_ASSERT_foo -: macro is defined, which can save you debugging time. -: -: Lines are of the form: +: WARNING: The meanings of some flags have been changed as of v5.31.0 + +: This file is known to be processed by regen/embed.pl, autodoc.pl, +: makedef.pl, Devel::PPPort, and porting/diag.t. +: +: All non-static functions defined by perl need to be listed in this file. +: embed.pl uses the entries here to construct proto.h to declare to the +: compiler the function interfaces, and embed.h to create macros that present a +: uniform interface to C code for the functions, regardless of, say, whether +: the perl is threaded or not. + +: Static functions need not appear here, but there is benefit to declaring them +: here, as it generally handles the thread context parameter invisibly, as well +: as making sure a PERL_ARGS_ASSERT_foo macro is defined, which can save you +: debugging time. +: +: Lines in this file are of the form: : flags|return_type|function_name|arg1|arg2|...|argN : -: A line may be continued on another by ending it with a backslash. +: A function taking no parameters will have no 'arg' elements. +: A line may be continued onto the next by ending it with a backslash. : Leading and trailing whitespace will be ignored in each component. : : The default without flags is to declare a function for internal perl-core use @@ -18,23 +28,52 @@ : modify this. Most non-static functions should have the 'p' flag to avoid : namespace clashes with programs that embed perl. : -: flags are single letters with following meanings: +: Scattered around the perl source are lines of the form: +: +: =for apidoc name +: +: and +: +: =for apidoc flags|return_type|name|arg1|arg2|...|argN +: +: and with the same meanings as the lines in this file. autodoc uses these +: lines in conjunction with this file to construct perlapi.pod. For entries of +: the first form, there must be a corresponding entry in this file, and the +: purpose of the line is to associate the pod accompanying it with the +: interface defined in this file. The second form is used to define the +: interface for the documentation when there is no entry in this file, hence it +: will be for something that isn't a non-static function: a macro of some kind, +: a constant, or some other entity that it wishes to have documented. (If +: there is also an entry in this file it overrides the apidoc line, and +: autodoc.pl will warn.) 'return_type' in these lines can be empty, unlike in +: this file. The entries in this file that have corresponding '=for apidoc' +: entries should have the flag 'd' set in this file. +: +: Devel::PPPort also looks at both this file and the '=for apidoc' lines. In +: part it is to construct lists of functions that are or are not backported. +: +: makedef.pl uses this file for constructing the export list +: +: porting/diag.t checks some things for consistency based on this file. +: +: 'flags' is a string of single letters. Most of the flags are meaningful only +: to embed.pl; some only to autodoc.pl, and others only to makedef.pl. The +: comments here don't include how Devel::PPPort or diag.t use them: : : A Available fully everywhere (usually part of the public API): : : add entry to the list of exported symbols (unless e or m); -: any doc entry goes in perlapi.pod rather than perlintern.pod. If no -: documentation is furnished for this function, and M is also -: specified, the function is not listed as part of the public API. -: If M isn't specified, and no documentation is furnished, the -: function is listed in perlapi as existing and being undocumented +: any doc entry goes in perlapi.pod rather than perlintern.pod. If +: none specified, autodoc.pl does not list this function/macro as +: part of the public API. If x isn't specified, and no +: documentation is furnished, autodoc.pl lists this in perlapi as +: existing and being undocumented. : makes '#define foo Perl_foo' scope not just for PERL_CORE/PERL_EXT : -: If the function is only exported for use in a public -: macro, see X. +: If the function is only exported for use in a public macro, see X. : : a Allocates memory a la malloc/calloc. Also implies "R". -: This should only be on functions which returns 'empty' memory +: This flag should only be on functions which return 'empty' memory : which has no other pointers to it, and which does not contain : any pointers to other things. So for example realloc() can't be : 'a'. @@ -60,7 +99,7 @@ : : For functions, like wrappers, whose macro shortcut doesn't call the : function, but which, for whatever reason, aren't considered legacy-only, -: use the 'o' flag +: use the 'o' flag, and maybe the 'M' : : This flag effectively causes nothing to happen if the perl interpreter : is compiled with -DNO_MATHOMS; otherwise these happen: @@ -71,21 +110,24 @@ : D Function is deprecated: : : proto.h: add __attribute__deprecated__ +: autodoc.pl adds a note to this effect in the doc entry : : d Function has documentation (somewhere) in the source: : -: enables 'no docs for foo" warning in autodoc.pl +: enables 'no docs for foo" warning in autodoc.pl in the documentation +: isn't found : : E Visible to extensions included in the Perl core: : : in embed.h, change "#ifdef PERL_CORE" : into "#if defined(PERL_CORE) || defined(PERL_EXT)" : -: To be usable from dynamically loaded extensions, either: -: 1) must be static to its containing file ("i" or "s" flag); or +: To be usable from dynamically loaded extensions, either: +: 1) it must be static to its containing file ("i" or "s" flag); or : 2) be combined with the "X" flag. : : e Not exported + : suppress entry in the list of exported symbols : : f Function takes a format string. If the function name =~ qr/strftime/ @@ -99,10 +141,16 @@ : : proto.h: function is declared as S_foo rather than foo unless the 'p' : flag is also given in which case 'Perl_foo' is used, -: PERL_STATIC_INLINE is added to declaration; +: PERL_STATIC_INLINE is added to the declaration : embed.h: "#define foo S_foo" or Perl_foo entries added : +: M There is an extra macro that bypasses this function : +: (requires 'p', and implies 'o') The function exists so that callers who +: used the 'Perl_' form can continue to do so, but there is a macro +: available without the 'Perl_' prefix that bypasses the function call, +: such as when the function has been reduced to a wrapper around another +: one. : : m Implemented as a macro: : @@ -111,11 +159,24 @@ : suppress entry in the list of exported symbols : suppress embed.h entry : +: N The name in the entry isn't strictly a name : +: Normally, the name of the function or macro must contain all \w +: characters, and a warning is raised otherwise. This flag suppresses +: that warning, so that weird things can be documented +: +: n Has no arguments (used only in =for apidoc entries) +: +: The macro (it can't be a function) is used without any parameters nor +: empty parentheses. : : O Has a perl_ compatibility macro. : -: The really OLD name for API funcs +: The really OLD name for API funcs. + +: autodoc.pl adds a note that the perl_ form of this function is +: deprecated. +: : : o Has no Perl_foo or S_foo compatibility macro: : @@ -123,10 +184,13 @@ : doesn't call the function specified by this entry. This is typically : done for a function that effectively just wraps another one, and where : the macro form calls the underlying function directly. For these, also -: specify the 'm' flag. Legacy-only functions should instead use 'b'. +: specify the 'M' flag. Legacy-only functions should instead use 'b'. : : embed.h: suppress "#define foo Perl_foo" : +: autodoc.pl adds a note that this function must be explicitly called as +: Perl_$name with an aTHX_ parameter, unless the 'M' flag is specified. +: : P Pure function: : : A pure function has no effects except the return value, and the return @@ -165,6 +229,9 @@ : STATIC is added to declaration; : embed.h: "#define foo S_foo" entries added : +: s autodoc.pl adds a terminating semi-colon to the usage example in the +: documentation. +: : T Has no implicit interpreter/thread context argument: : : suppress the pTHX part of "foo(pTHX...)" in proto.h; @@ -172,9 +239,7 @@ : "#define foo Perl_foo", rather than : "#define foo(a,b,c) Perl_foo(aTHX_ a,b,c) : -: U Suppress usage example in autogenerated documentation -: -: (currently no effect) +: U autodoc.pl will not output a usage example : : W Add a _pDEPTH argument to function prototypes, and an _aDEPTH : argument to the function calls. This means that under DEBUGGING @@ -196,16 +261,15 @@ : any doc entry is marked that it may change. Also used to suppress : making a doc entry if it would just be a placeholder. : -: (see also L for those flags.) -: -: Pointer parameters that must not be passed NULLs should be prefixed with NN. +: In this file, pointer parameters that must not be passed NULLs should be +: prefixed with NN. : -: Pointer parameters that may be NULL should be prefixed with NULLOK. This has -: no effect on output yet. It's a notation for the maintainers to know "I have -: defined whether NULL is OK or not" rather than having neither NULL or NULLOK, -: which is ambiguous. +: And, pointer parameters that may be NULL should be prefixed with NULLOK. +: This has no effect on output yet. It's a notation for the maintainers to +: know "I have defined whether NULL is OK or not" rather than having neither +: NULL or NULLOK, which is ambiguous. : -: Individual flags may be separated by whitespace. +: Individual flags may be separated by non-tab whitespace. #if defined(PERL_IMPLICIT_SYS) ATo |PerlInterpreter*|perl_alloc_using \ @@ -671,7 +735,7 @@ Ap |void* |hv_common |NULLOK HV *hv|NULLOK SV *keysv \ Ap |void* |hv_common_key_len|NULLOK HV *hv|NN const char *key \ |I32 klen_i32|const int action|NULLOK SV *val \ |const U32 hash -Apod |STRLEN |hv_fill |NN HV *const hv +AMpod |STRLEN |hv_fill |NN HV *const hv Ap |void |hv_free_ent |NN HV *hv|NULLOK HE *entry Apd |I32 |hv_iterinit |NN HV *hv ApdR |char* |hv_iterkey |NN HE* entry|NN I32* retlen @@ -1171,7 +1235,7 @@ pX |CV * |newXS_deffile |NN const char *name|NN XSUBADDR_t subaddr Apx |CV * |newXS_flags |NULLOK const char *name|NN XSUBADDR_t subaddr\ |NN const char *const filename \ |NULLOK const char *const proto|U32 flags -Apd |CV* |newXS |NULLOK const char *name|NN XSUBADDR_t subaddr\ +ApdU |CV* |newXS |NULLOK const char *name|NN XSUBADDR_t subaddr\ |NN const char *filename ApmdbR |AV* |newAV ApR |OP* |newAVREF |NN OP* o @@ -1256,13 +1320,8 @@ Apd |SV* |vstringify |NN SV *vs Apd |int |vcmp |NN SV *lhv|NN SV *rhv : Used in pp_hot.c and pp_sys.c p |PerlIO*|nextargv |NN GV* gv|bool nomagicopen -#ifdef HAS_MEMMEM -AdTopP |char* |ninstr |NN const char* big|NN const char* bigend \ +AdMTpP |char* |ninstr |NN const char* big|NN const char* bigend \ |NN const char* little|NN const char* lend -#else -AdTpP |char* |ninstr |NN const char* big|NN const char* bigend \ - |NN const char* little|NN const char* lend -#endif Apd |void |op_free |NULLOK OP* arg xp |OP* |op_unscope |NULLOK OP* o #ifdef PERL_CORE @@ -1581,10 +1640,10 @@ Apd |void |sv_clear |NN SV *const orig_sv #if defined(PERL_IN_SV_C) S |bool |curse |NN SV * const sv|const bool check_refcnt #endif -Aopd |I32 |sv_cmp |NULLOK SV *const sv1|NULLOK SV *const sv2 +AMopd |I32 |sv_cmp |NULLOK SV *const sv1|NULLOK SV *const sv2 Apd |I32 |sv_cmp_flags |NULLOK SV *const sv1|NULLOK SV *const sv2 \ |const U32 flags -Aopd |I32 |sv_cmp_locale |NULLOK SV *const sv1|NULLOK SV *const sv2 +AMopd |I32 |sv_cmp_locale |NULLOK SV *const sv1|NULLOK SV *const sv2 Apd |I32 |sv_cmp_locale_flags |NULLOK SV *const sv1 \ |NULLOK SV *const sv2|const U32 flags #if defined(USE_LOCALE_COLLATE) @@ -1859,7 +1918,7 @@ AipdRT |U8* |utf8_hop_safe |NN const U8 *s|SSize_t off|NN const U8 *start|NN con Apxd |U8* |utf8_to_bytes |NN U8 *s|NN STRLEN *lenp Apd |int |bytes_cmp_utf8 |NN const U8 *b|STRLEN blen|NN const U8 *u \ |STRLEN ulen -Axodp |U8* |bytes_from_utf8|NN const U8 *s|NN STRLEN *lenp|NN bool *is_utf8p +AMxdp |U8* |bytes_from_utf8|NN const U8 *s|NN STRLEN *lenp|NN bool *is_utf8p AxTp |U8* |bytes_from_utf8_loc|NN const U8 *s \ |NN STRLEN *lenp \ |NN bool *is_utf8p \ @@ -1868,15 +1927,15 @@ Apxd |U8* |bytes_to_utf8 |NN const U8 *s|NN STRLEN *lenp ApdD |UV |utf8_to_uvchr |NN const U8 *s|NULLOK STRLEN *retlen AbpdD |UV |utf8_to_uvuni |NN const U8 *s|NULLOK STRLEN *retlen AbpxD |UV |valid_utf8_to_uvuni |NN const U8 *s|NULLOK STRLEN *retlen -Aopd |UV |utf8_to_uvchr_buf |NN const U8 *s|NN const U8 *send|NULLOK STRLEN *retlen +AMpd |UV |utf8_to_uvchr_buf |NN const U8 *s|NN const U8 *send|NULLOK STRLEN *retlen ApdD |UV |utf8_to_uvuni_buf |NN const U8 *s|NN const U8 *send|NULLOK STRLEN *retlen px |bool |check_utf8_print |NN const U8 *s|const STRLEN len -AdTop |UV |utf8n_to_uvchr |NN const U8 *s \ +AdMTp |UV |utf8n_to_uvchr |NN const U8 *s \ |STRLEN curlen \ |NULLOK STRLEN *retlen \ |const U32 flags -AdTop |UV |utf8n_to_uvchr_error|NN const U8 *s \ +AdMTp |UV |utf8n_to_uvchr_error|NN const U8 *s \ |STRLEN curlen \ |NULLOK STRLEN *retlen \ |const U32 flags \ @@ -1901,7 +1960,7 @@ Adm |U8* |uvchr_to_utf8 |NN U8 *d|UV uv Ap |U8* |uvuni_to_utf8 |NN U8 *d|UV uv Adm |U8* |uvchr_to_utf8_flags |NN U8 *d|UV uv|UV flags Admx |U8* |uvchr_to_utf8_flags_msgs|NN U8 *d|UV uv|UV flags|NULLOK HV ** msgs -Apod |U8* |uvoffuni_to_utf8_flags |NN U8 *d|UV uv|const UV flags +AMpod |U8* |uvoffuni_to_utf8_flags |NN U8 *d|UV uv|const UV flags Apx |U8* |uvoffuni_to_utf8_flags_msgs|NN U8 *d|UV uv|const UV flags|NULLOK HV** msgs Ap |U8* |uvuni_to_utf8_flags |NN U8 *d|UV uv|UV flags Apd |char* |pv_uni_display |NN SV *dsv|NN const U8 *spv|STRLEN len|STRLEN pvlim|UV flags @@ -3131,8 +3190,8 @@ ApoP |bool |ckwarn_d |U32 w XEopxR |STRLEN *|new_warnings_bitfield|NULLOK STRLEN *buffer \ |NN const char *const bits|STRLEN size -ApTodf |int |my_snprintf |NN char *buffer|const Size_t len|NN const char *format|... -ApTod |int |my_vsnprintf |NN char *buffer|const Size_t len|NN const char *format|va_list ap +AMpTodf |int |my_snprintf |NN char *buffer|const Size_t len|NN const char *format|... +AMpTod |int |my_vsnprintf |NN char *buffer|const Size_t len|NN const char *format|va_list ap #ifdef USE_QUADMATH ApTd |const char* |quadmath_format_single|NN const char* format ApTd |bool|quadmath_format_needed|NN const char* format @@ -3157,15 +3216,15 @@ XpoT |I32 |xs_handshake |const U32 key|NN void * v_my_perl\ |NN const char * file| ... Xp |void |xs_boot_epilog |const I32 ax #ifndef HAS_STRLCAT -ApTod |Size_t |my_strlcat |NULLOK char *dst|NULLOK const char *src|Size_t size +ApTd |Size_t |my_strlcat |NULLOK char *dst|NULLOK const char *src|Size_t size #endif #ifndef HAS_STRLCPY -ApTod |Size_t |my_strlcpy |NULLOK char *dst|NULLOK const char *src|Size_t size +ApTd |Size_t |my_strlcpy |NULLOK char *dst|NULLOK const char *src|Size_t size #endif #ifndef HAS_STRNLEN -ApTod |Size_t |my_strnlen |NN const char *str|Size_t maxlen +ApTd |Size_t |my_strnlen |NN const char *str|Size_t maxlen #endif #ifndef HAS_MKOSTEMP @@ -3225,10 +3284,10 @@ p |void |boot_core_mro ApoT |void |sys_init |NN int* argc|NN char*** argv ApoT |void |sys_init3 |NN int* argc|NN char*** argv|NN char*** env ApoT |void |sys_term -Apox |const char *|cop_fetch_label|NN COP *const cop \ +AMpx |const char *|cop_fetch_label|NN COP *const cop \ |NULLOK STRLEN *len|NULLOK U32 *flags : Only used in op.c and the perl compiler -Apox |void|cop_store_label \ +AMpx |void|cop_store_label \ |NN COP *const cop|NN const char *label|STRLEN len|U32 flags epo |int |keyword_plugin_standard|NN char* keyword_ptr|STRLEN keyword_len|NN OP** op_ptr