: BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl.
:
: 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.
:
: 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
: Lines in this file are of the form:
: flags|return_type|function_name|arg1|arg2|...|argN
:
+: '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 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
-: only, not visible to XS code nor to Perl extensions. Use the A and E flags to
-: modify this. Most non-static functions should have the 'p' flag to avoid
-: namespace clashes with programs that embed perl.
+: only. On some platforms, such as Linux and Darwin, all non-static functions
+: are currently externally visible. Because of this, and also for programs
+: that embed perl, most non-static functions should have the 'p' flag to avoid
+: namespace clashes.
+:
+: Most entries here have a macro created to wrap them, and whose name doesn't
+: include the 'Perl_', or other prefix.
:
: Scattered around the perl source are lines of the form:
:
: =for apidoc name
:
-: and
+: followed by pod for that function. The purpose of these is to tell
+: autodoc.pl where the documentation is for a function listed in this file. It
+: uses the prototype from here and the pod from there in generating the
+: documentation in perlapi or perlintern. The entries in this file that have
+: corresponding '=for apidoc' entries should have the flag 'd' set in this
+: file.
+:
+: There are also lines of this form scattered around:
:
: =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.
+: and with the same meanings as the lines in this file. The 'name' in any such
+: line must not be the same as any in this file (i.e., no redundant
+: definitions), and one of the flags must be 'm', indicating this is a macro.
+: The lines following these are pod for the respective macro. Since these are
+: macros, the arguments need not be legal C parameters. To indicate this to
+: downstream software that inspects these lines, there are a few conventions:
+: type should be the entire argument name if it names a type
+: cast should be the entire argument name if it is a cast
+: SP should be the entire argument name if it is the stack pointer SP
+: block should be the entire argument name if it is a C brace-enclosed block
+:
+: The letters above are exact. For example, you have to have 't', 'y', 'p',
+: and 'e' literally. Here is an example:
+: =for apidoc Am|void|Newxc|void* ptr|int nitems|type|cast
+:
+: Additionally, an argument can be some word(s) enclosed in double quotes to
+: indicate that it has to be a string, instead of a const char * const, like this
+: =for apidoc Ama|SV*|newSVpvs|"string"
+:
+: Again, autodoc uses these lines to construct perlapi. 'return_type' in these
+: lines can be empty, unlike 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.
:
: 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 Accessible fully everywhere (usually part of the public API):
:
: add entry to the list of exported symbols (unless e or m);
: 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/
: O Has a perl_ compatibility macro.
:
: The really OLD name for API funcs.
-
+:
: autodoc.pl adds a note that the perl_ form of this function is
: deprecated.
:
: "#define foo Perl_foo", rather than
: "#define foo(a,b,c) Perl_foo(aTHX_ a,b,c)
:
+: u The macro's (it has to be a macro) return value or parameters are
+: unorthodox, and aren't in the list above of recognized weird ones. For
+: example, they aren't C parameters, or the macro expands to something
+: that isn't a symbol.
+:
+: For example, the expansion of STR_WITH_LEN is a comma separated pair of
+: values, so would have this flag; or some macros take preprocessor
+: tokens, so would have this flag. This flag is an indication to
+: downstream tools, such as Devel::PPPort, that this requires special
+: handling.
+:
: U autodoc.pl will not output a usage example
:
: W Add a _pDEPTH argument to function prototypes, and an _aDEPTH
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
-Ap |SV* |filter_add |NULLOK filter_t funcp|NULLOK SV* datasv
+Aphd |SV* |filter_add |NULLOK filter_t funcp|NULLOK SV* datasv
Ap |void |filter_del |NN filter_t funcp
-ApR |I32 |filter_read |int idx|NN SV *buf_sv|int maxlen
+ApRhd |I32 |filter_read |int idx|NN SV *buf_sv|int maxlen
ApPR |char** |get_op_descs
ApPR |char** |get_op_names
: FIXME discussion on p5p
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
-AMpod |STRLEN |hv_fill |NN HV *const hv
+Apod |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
ApdR |I32 |looks_like_number|NN SV *const sv
Apd |UV |grok_bin |NN const char* start|NN STRLEN* len_p|NN I32* flags|NULLOK NV *result
#if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_TOKE_C) || defined(PERL_IN_DQUOTE_C)
-ExpRX |bool |grok_bslash_x |NN char** s \
+EpRX |bool |grok_bslash_x |NN char** s \
|NN const char* const send \
|NN UV* uv \
|NN const char** error_msg \
|const bool strict \
|const bool silence_non_portable \
|const bool utf8
-ExpRX |char |grok_bslash_c |const char source|const bool output_warning
-ExpRX |bool |grok_bslash_o |NN char** s \
+EpRX |char |grok_bslash_c |const char source|const bool output_warning
+EpRX |bool |grok_bslash_o |NN char** s \
|NN const char* const send \
|NN UV* uv \
|NN const char** error_msg \
|const bool strict \
|const bool silence_non_portable \
|const bool utf8
-ExiR |char*|form_short_octal_warning|NN const char * const s \
+EiR |char*|form_short_octal_warning|NN const char * const s \
|const STRLEN len
EiRT |I32 |regcurly |NN const char *s
#endif
#endif
Ap |void |pop_scope
Ap |void |push_scope
+#if defined(PERL_IN_PERLY_C) || defined(PERL_IN_OP_C) || defined(PERL_IN_TOKE_C)
ApMb |OP* |ref |NULLOK OP* o|I32 type
+#endif
#if defined(PERL_IN_OP_C)
S |OP* |refkids |NULLOK OP* o|I32 type
#endif
Ap |void |regdump |NN const regexp* r
#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
-EXxp |bool |_invlistEQ |NN SV* const a|NN SV* const b|const bool complement_b
+EXp |bool |_invlistEQ |NN SV* const a|NN SV* const b|const bool complement_b
#endif
Ap |I32 |pregexec |NN REGEXP * const prog|NN char* stringarg \
|NN char* strend|NN char* strbeg \
Ap |void |save_aelem_flags|NN AV* av|SSize_t idx|NN SV **sptr \
|const U32 flags
Ap |I32 |save_alloc |I32 size|I32 pad
-Ap |void |save_aptr |NN AV** aptr
-Ap |AV* |save_ary |NN GV* gv
+Apdh |void |save_aptr |NN AV** aptr
+Apdh |AV* |save_ary |NN GV* gv
Ap |void |save_bool |NN bool* boolp
Ap |void |save_clearsv |NN SV** svp
Ap |void |save_delete |NN HV *hv|NN char *key|I32 klen
Ap |void |save_generic_pvref|NN char** str
Ap |void |save_shared_pvref|NN char** str
Adp |void |save_gp |NN GV* gv|I32 empty
-Ap |HV* |save_hash |NN GV* gv
+Apdh |HV* |save_hash |NN GV* gv
Ap |void |save_hints
Amp |void |save_helem |NN HV *hv|NN SV *key|NN SV **sptr
Ap |void |save_helem_flags|NN HV *hv|NN SV *key|NN SV **sptr|const U32 flags
-Ap |void |save_hptr |NN HV** hptr
+Apdh |void |save_hptr |NN HV** hptr
Ap |void |save_I16 |NN I16* intp
Ap |void |save_I32 |NN I32* intp
Ap |void |save_I8 |NN I8* bytep
Ap |void |save_int |NN int* intp
-Ap |void |save_item |NN SV* item
+Apdh |void |save_item |NN SV* item
Ap |void |save_iv |NN IV *ivp
-AbpD |void |save_list |NN SV** sarg|I32 maxsarg
+AbpDdh |void |save_list |NN SV** sarg|I32 maxsarg
AbpD |void |save_long |NN long* longp
ApMb |void |save_mortalizesv|NN SV* sv
AbpD |void |save_nogv |NN GV* gv
: Used in SAVEFREOP(), used in gv.c, op.c, perl.c, pp_ctl.c, pp_sort.c
ApMb |void |save_op
-Ap |SV* |save_scalar |NN GV* gv
+Apdh |SV* |save_scalar |NN GV* gv
Ap |void |save_pptr |NN char** pptr
Ap |void |save_vptr |NN void *ptr
Ap |void |save_re_context
Ap |void |save_padsv_and_mortalize|PADOFFSET off
Ap |void |save_sptr |NN SV** sptr
Xp |void |save_strlen |NN STRLEN* ptr
-Ap |SV* |save_svref |NN SV** sptr
+Apdh |SV* |save_svref |NN SV** sptr
Axpo |void |savetmps
Ap |void |save_pushptr |NULLOK void *const ptr|const int type
Ap |void |save_pushi32ptr|const I32 i|NULLOK void *const ptr|const int type
|NULLOK va_list *const args|NULLOK SV **const svargs \
|const Size_t sv_count|NULLOK bool *const maybe_tainted
ApR |NV |str_to_version |NN SV *sv
-EXpRx |SV* |swash_init |NN const char* pkg|NN const char* name|NN SV* listsv|I32 minbits|I32 none
-EXpx |UV |swash_fetch |NN SV *swash|NN const U8 *ptr|bool do_utf8
+EXpR |SV* |swash_init |NN const char* pkg|NN const char* name|NN SV* listsv|I32 minbits|I32 none
+EXp |UV |swash_fetch |NN SV *swash|NN const U8 *ptr|bool do_utf8
#ifdef PERL_IN_REGCOMP_C
-EixR |SV* |add_cp_to_invlist |NULLOK SV* invlist|const UV cp
-EixRT |bool |invlist_is_iterating|NN SV* const invlist
+EiR |SV* |add_cp_to_invlist |NULLOK SV* invlist|const UV cp
+EiRT |bool |invlist_is_iterating|NN SV* const invlist
#ifndef PERL_EXT_RE_BUILD
-EixRT |UV* |_invlist_array_init |NN SV* const invlist|const bool will_have_0
-EixRT |UV |invlist_max |NN SV* const invlist
-ESx |void |_append_range_to_invlist |NN SV* const invlist|const UV start|const UV end
-ESx |void |invlist_extend |NN SV* const invlist|const UV len
-ESx |void |invlist_replace_list_destroys_src|NN SV *dest|NN SV *src
-EixRT |IV* |get_invlist_previous_index_addr|NN SV* invlist
-Eix |void |invlist_set_len|NN SV* const invlist|const UV len|const bool offset
-EixT |void |invlist_set_previous_index|NN SV* const invlist|const IV index
-EixRT |IV |invlist_previous_index|NN SV* const invlist
-EixT |void |invlist_trim |NN SV* invlist
-Eix |void |invlist_clear |NN SV* invlist
-Sx |void |initialize_invlist_guts|NN SV* invlist|const Size_t initial_size
-#endif
-EixRT |STRLEN*|get_invlist_iter_addr |NN SV* invlist
-EixT |void |invlist_iterinit|NN SV* invlist
-ESxRT |bool |invlist_iternext|NN SV* invlist|NN UV* start|NN UV* end
-EixT |void |invlist_iterfinish|NN SV* invlist
-EixRT |UV |invlist_highest|NN SV* const invlist
-ExRS |SV* |_make_exactf_invlist |NN RExC_state_t *pRExC_state \
+EiRT |UV* |_invlist_array_init |NN SV* const invlist|const bool will_have_0
+EiRT |UV |invlist_max |NN SV* const invlist
+ES |void |_append_range_to_invlist |NN SV* const invlist|const UV start|const UV end
+ES |void |invlist_extend |NN SV* const invlist|const UV len
+ES |void |invlist_replace_list_destroys_src|NN SV *dest|NN SV *src
+EiRT |IV* |get_invlist_previous_index_addr|NN SV* invlist
+Ei |void |invlist_set_len|NN SV* const invlist|const UV len|const bool offset
+EiT |void |invlist_set_previous_index|NN SV* const invlist|const IV index
+EiRT |IV |invlist_previous_index|NN SV* const invlist
+EiT |void |invlist_trim |NN SV* invlist
+Ei |void |invlist_clear |NN SV* invlist
+S |void |initialize_invlist_guts|NN SV* invlist|const Size_t initial_size
+#endif
+EiRT |STRLEN*|get_invlist_iter_addr |NN SV* invlist
+EiT |void |invlist_iterinit|NN SV* invlist
+ESRT |bool |invlist_iternext|NN SV* invlist|NN UV* start|NN UV* end
+EiT |void |invlist_iterfinish|NN SV* invlist
+EiRT |UV |invlist_highest|NN SV* const invlist
+ERS |SV* |_make_exactf_invlist |NN RExC_state_t *pRExC_state \
|NN regnode *node
-ESxR |SV* |invlist_contents|NN SV* const invlist \
+ESR |SV* |invlist_contents|NN SV* const invlist \
|const bool traditional_style
ESRT |bool |new_regcurly |NN const char *s|NN const char *e
#endif
#if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_UTF8_C)
-EXmx |void |_invlist_intersection |NN SV* const a|NN SV* const b|NN SV** i
-EXpx |void |_invlist_intersection_maybe_complement_2nd \
+EXm |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
-EXmx |void |_invlist_union |NULLOK SV* const a|NN SV* const b|NN SV** output
-EXpx |void |_invlist_union_maybe_complement_2nd \
+EXm |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
-EXmx |void |_invlist_subtract|NN SV* const a|NN SV* const b|NN SV** result
-EXpx |void |_invlist_invert|NN SV* const invlist
-EXxpR |SV* |_new_invlist |IV initial_size
-EXxpR |SV* |_add_range_to_invlist |NULLOK SV* invlist|UV start|UV end
-EXxpR |SV* |_setup_canned_invlist|const STRLEN size|const UV element0|NN UV** other_elements_ptr
+EXm |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
+EXpR |SV* |_setup_canned_invlist|const STRLEN size|const UV element0|NN UV** other_elements_ptr
#endif
#if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_SV_C)
-ExpX |SV* |invlist_clone |NN SV* const invlist|NULLOK SV* newlist
+EpX |SV* |invlist_clone |NN SV* const invlist|NULLOK SV* newlist
#endif
#if defined(PERL_IN_REGCOMP_C) || defined(PERL_IN_REGEXEC_C) || defined(PERL_IN_TOKE_C) || defined(PERL_IN_UTF8_C) || defined(PERL_IN_PP_C)
-EixRT |UV* |invlist_array |NN SV* const invlist
-EixRT |bool |is_invlist |NULLOK SV* const invlist
-EixRT |bool* |get_invlist_offset_addr|NN SV* invlist
-EixRT |UV |_invlist_len |NN SV* const invlist
-ExiRT |bool |_invlist_contains_cp|NN SV* const invlist|const UV cp
-EXpxRT |SSize_t|_invlist_search |NN SV* const invlist|const UV cp
+EiRT |UV* |invlist_array |NN SV* const invlist
+EiRT |bool |is_invlist |NULLOK SV* const invlist
+EiRT |bool* |get_invlist_offset_addr|NN SV* invlist
+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_REGCOMP_C) || defined(PERL_IN_REGEXEC_C)
-EXpx |SV* |_get_regclass_nonbitmap_data \
+EXp |SV* |_get_regclass_nonbitmap_data \
|NULLOK const regexp *prog \
|NN const struct regnode *node \
|bool doinit \
|NULLOK SV **output_invlist
#endif
#if defined(PERL_IN_REGCOMP_C) || defined (PERL_IN_DUMP_C)
-EXxp |void |_invlist_dump |NN PerlIO *file|I32 level \
+EXp |void |_invlist_dump |NN PerlIO *file|I32 level \
|NN const char* const indent \
|NN SV* const invlist
#endif
AMpd |UV |utf8_to_uvchr_buf |NN const U8 *s|NN const U8 *send|NULLOK STRLEN *retlen
Ai |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
+p |bool |check_utf8_print |NN const U8 *s|const STRLEN len
AdMTp |UV |utf8n_to_uvchr |NN const U8 *s \
|STRLEN curlen \
SR |HV * |new_msg_hv |NN const char * const message \
|U32 categories \
|U32 flag
-SRx |UV |check_locale_boundary_crossing \
+SR |UV |check_locale_boundary_crossing \
|NN const U8* const p \
|const UV result \
|NN U8* const ustrp \
|NN const U8 *const e \
|NULLOK SV* const invlist
SR |SV* |swatch_get |NN SV* swash|UV start|UV span
-SRx |U8* |swash_scan_list_line|NN U8* l|NN U8* const lend|NN UV* min \
+SR |U8* |swash_scan_list_line|NN U8* l|NN U8* const lend|NN UV* min \
|NN UV* max|NN UV* val|const bool wants_value \
|NN const U8* const typestr
#endif
-EXixT |void |append_utf8_from_native_byte|const U8 byte|NN U8** dest
+EXiT |void |append_utf8_from_native_byte|const U8 byte|NN U8** dest
Apd |void |sv_set_undef |NN SV *sv
Apd |void |sv_setsv_flags |NN SV *dstr|NULLOK SV *sstr|const I32 flags
: Used by SvRX and SvRXOK
XExop |REGEXP *|get_re_arg|NULLOK SV *sv
-Aop |SV* |mro_get_private_data|NN struct mro_meta *const smeta \
+Aopdh |SV* |mro_get_private_data|NN struct mro_meta *const smeta \
|NN const struct mro_alg *const which
-Aop |SV* |mro_set_private_data|NN struct mro_meta *const smeta \
+Aopdh |SV* |mro_set_private_data|NN struct mro_meta *const smeta \
|NN const struct mro_alg *const which \
|NN SV *const data
Aop |const struct mro_alg *|mro_get_from_name|NN SV *name
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
-AMpxd |const char *|cop_fetch_label|NN COP *const cop \
+Apxd |const char *|cop_fetch_label|NN COP *const cop \
|NULLOK STRLEN *len|NULLOK U32 *flags
: Only used in op.c and the perl compiler
-AMpxd |void|cop_store_label \
+Apxd |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