: 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
: 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'.
:
: 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:
: 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/
:
: 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:
:
: 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:
:
: 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
: 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;
: "#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
: 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<perlguts/Internal Functions> 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 \
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
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
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
#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)
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 \
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 \
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
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
|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
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
https://perl5.git.perl.org / perl5.git / blobdiff