X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a04ef3ff46f2526da1484bdd80995415ac7e1969..4294a0edb4e7ea798913132a58f8f3c8995350f2:/perl.h diff --git a/perl.h b/perl.h index 88d0511..4829578 100644 --- a/perl.h +++ b/perl.h @@ -83,6 +83,33 @@ /* <--- here ends the logic shared by perl.h and makedef.pl */ +/* +=for apidoc_section Compiler directives +=for apidoc AmnUu|void|EXTERN_C +When not compiling using C++, expands to nothing. +Otherwise is used in a declaration of a function to indicate the function +should have external C linkage. This is required for things to work for just +about all functions with external linkage compiled into perl. +Often, you can use C> ... C> blocks +surrounding all your code that you need to have this linkage. + +Example usage: + + EXTERN_C int flock(int fd, int op); + +=for apidoc Amnu||START_EXTERN_C +When not compiling using C++, expands to nothing. +Otherwise begins a section of code in which every function will effectively +have C> applied to it, that is to have external C linkage. The +section is ended by a C>. + +=for apidoc Amnu||END_EXTERN_C +When not compiling using C++, expands to nothing. +Otherwise ends a section of code already begun by a C>. + +=cut +*/ + #undef START_EXTERN_C #undef END_EXTERN_C #undef EXTERN_C @@ -153,6 +180,14 @@ * implementation of multiplicity using C++ objects. They have been left * here solely for the sake of XS code which has incorrectly * cargo-culted them. + * + * The only one Devel::PPPort handles is this; list it as deprecated + +=for apidoc_section Concurrency +=for apidoc AmD|void|CPERLscope|void x +Now a no-op. + +=cut */ #define CPERLscope(x) x #define CPERLarg void @@ -370,7 +405,25 @@ * marking unused variables (they need e.g. a #pragma) and therefore * cpp macros like PERL_UNUSED_DECL cannot work for this purpose, even * if it were PERL_UNUSED_DECL(x), which it cannot be (see above). - * + +=for apidoc_section Compiler directives +=for apidoc AmnU||PERL_UNUSED_DECL +Tells the compiler that the parameter in the function prototype just before it +is not necessarily expected to be used in the function. Not that many +compilers understand this, so this should only be used in cases where +C> can't conveniently be used. + +Example usage: + +=over + + Signal_t + Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL, + void *uap PERL_UNUSED_DECL, bool safe) + +=back + +=cut */ #ifndef PERL_UNUSED_DECL @@ -381,6 +434,24 @@ * for silencing unused variables that are actually used most of the time, * but we cannot quite get rid of, such as "ax" in PPCODE+noargs xsubs, * or variables/arguments that are used only in certain configurations. + +=for apidoc Ams||PERL_UNUSED_ARG|void x +This is used to suppress compiler warnings that a parameter to a function is +not used. This situation can arise, for example, when a parameter is needed +under some configuration conditions, but not others, so that C preprocessor +conditional compilation causes it be used just some times. + +=for apidoc Amns||PERL_UNUSED_CONTEXT +This is used to suppress compiler warnings that the thread context parameter to +a function is not used. This situation can arise, for example, when a +C preprocessor conditional compilation causes it be used just some times. + +=for apidoc Ams||PERL_UNUSED_VAR|void x +This is used to suppress compiler warnings that the variable I is not used. +This situation can arise, for example, when a C preprocessor conditional +compilation causes it be used just some times. + +=cut */ #ifndef PERL_UNUSED_ARG # define PERL_UNUSED_ARG(x) ((void)sizeof(x)) @@ -408,31 +479,40 @@ # endif #endif -/* Use PERL_UNUSED_RESULT() to suppress the warnings about unused results - * of function calls, e.g. PERL_UNUSED_RESULT(foo(a, b)). - * - * The main reason for this is that the combination of gcc -Wunused-result - * (part of -Wall) and the __attribute__((warn_unused_result)) cannot - * be silenced with casting to void. This causes trouble when the system - * header files use the attribute. - * - * Use PERL_UNUSED_RESULT sparingly, though, since usually the warning - * is there for a good reason: you might lose success/failure information, - * or leak resources, or changes in resources. - * - * But sometimes you just want to ignore the return value, e.g. on - * codepaths soon ending up in abort, or in "best effort" attempts, - * or in situations where there is no good way to handle failures. - * - * Sometimes PERL_UNUSED_RESULT might not be the most natural way: - * another possibility is that you can capture the return value - * and use PERL_UNUSED_VAR on that. - * - * The __typeof__() is used instead of typeof() since typeof() is not - * available under strict C89, and because of compilers masquerading - * as gcc (clang and icc), we want exactly the gcc extension - * __typeof__ and nothing else. - */ +/* + +=for apidoc Am||PERL_UNUSED_RESULT|void x + +This macro indicates to discard the return value of the function call inside +it, I, + + PERL_UNUSED_RESULT(foo(a, b)) + +The main reason for this is that the combination of C +(part of C<-Wall>) and the C<__attribute__((warn_unused_result))> cannot +be silenced with casting to C. This causes trouble when the system +header files use the attribute. + +Use C sparingly, though, since usually the warning +is there for a good reason: you might lose success/failure information, +or leak resources, or changes in resources. + +But sometimes you just want to ignore the return value, I, on +codepaths soon ending up in abort, or in "best effort" attempts, +or in situations where there is no good way to handle failures. + +Sometimes C might not be the most natural way: +another possibility is that you can capture the return value +and use C> on that. + +=cut + +The __typeof__() is used instead of typeof() since typeof() is not +available under strict C89, and because of compilers masquerading +as gcc (clang and icc), we want exactly the gcc extension +__typeof__ and nothing else. + +*/ #ifndef PERL_UNUSED_RESULT # if defined(__GNUC__) && defined(HASATTRIBUTE_WARN_UNUSED_RESULT) # define PERL_UNUSED_RESULT(v) STMT_START { __typeof__(v) z = (v); (void)sizeof(z); } STMT_END @@ -578,20 +658,41 @@ #endif /* -=head1 Miscellaneous Functions - +=for apidoc_section Compiler directives =for apidoc AmnUu|void|STMT_START +=for apidoc_item ||STMT_END + +This allows a series of statements in a macro to be used as a single statement, +as in + + if (x) STMT_START { ... } STMT_END else ... + +Note that you can't return a value out of them, which limits their utility. +But see C>. - STMT_START { statements; } STMT_END; +=for apidoc AmnuU|bool|PERL_USE_GCC_BRACE_GROUPS -can be used as a single statement, as in +This C pre-processor value, if defined, indicates that it is permissible to use +the GCC brace groups extension. This extension, of the form - if (x) STMT_START { ... } STMT_END; else ... + ({ statement ... }) -These are often used in macro definitions. Note that you can't return a value -out of them. +turns the block consisting of I into an expression with a +value, unlike plain C language blocks. This can present optimization +possibilities, B you generally need to specify an alternative in case this +ability doesn't exist or has otherwise been forbidden. -=for apidoc AmnUhu|void|STMT_END +Example usage: + +=over + + #ifdef PERL_USE_GCC_BRACE_GROUPS + ... + #else + ... + #endif + +=back =cut @@ -1011,6 +1112,25 @@ EXTERN_C int usleep(unsigned int); # define UINT64_C(c) PeRl_UINT64_C(c) # endif +/* +=for apidoc_section Integer configuration values +=for apidoc Am||INTMAX_C|number +Returns a token the C compiler recognizes for the constant C of the +widest integer type on the machine. For example, if the machine has Cs, C would yield + + -1LL + +=for apidoc Am||UINTMAX_C|number +Returns a token the C compiler recognizes for the constant C of the +widest unsigned integer type on the machine. For example, if the machine has +Cs, C would yield + + 1UL + +=cut +*/ + # ifndef I_STDINT typedef I64TYPE PERL_INTMAX_T; typedef U64TYPE PERL_UINTMAX_T; @@ -1322,7 +1442,7 @@ EXTERN_C char *crypt(const char *, const char *); #endif /* -=head1 Errno +=for apidoc_section Errno =for apidoc m|void|SETERRNO|int errcode|int vmserrcode @@ -1425,7 +1545,7 @@ was saved by C or C. #endif /* -=head1 Warning and Dieing +=for apidoc_section Warning and Dieing =for apidoc Amn|SV *|ERRSV @@ -1502,6 +1622,20 @@ any magic. # define SAVE_DEFSV SAVESPTR(GvSV(PL_defgv)) #endif +/* +=for apidoc_section SV Handling +=for apidoc Amn|SV *|DEFSV +Returns the SV associated with C<$_> + +=for apidoc Am|void|DEFSV_set|SV * sv +Associate C with C<$_> + +=for apidoc Amn|void|SAVE_DEFSV +Localize C<$_>. See L. + +=cut +*/ + #ifndef errno extern int errno; /* ANSI allows errno to be an lvalue expr. * For example in multithreaded environments @@ -1711,8 +1845,7 @@ any magic. * longer need that. XS modules can (and do) use this name, so it must remain * a part of the API that's visible to modules. -=head1 Miscellaneous Functions - +=for apidoc_section String Handling =for apidoc ATmD|int|my_sprintf|NN char *buffer|NN const char *pat|... Do NOT use this due to the possibility of overflowing C. Instead use @@ -1902,6 +2035,8 @@ typedef UVTYPE UV; * For int conversions we do not need two casts if pointers are * the same size as IV and UV. Otherwise we need an explicit * cast (PTRV) to avoid compiler warnings. + * + * These are mentioned in perlguts */ #if (IVSIZE == PTRSIZE) && (UVSIZE == PTRSIZE) # define PTRV UV @@ -2534,43 +2669,28 @@ extern long double Perl_my_frexpl(long double x, int *e); #endif /* -=head1 Numeric functions - -=for apidoc AmnUh||PERL_INT_MIN -=for apidoc AmnUh||PERL_LONG_MAX -=for apidoc AmnUh||PERL_LONG_MIN -=for apidoc AmnUh||PERL_QUAD_MAX -=for apidoc AmnUh||PERL_SHORT_MAX -=for apidoc AmnUh||PERL_SHORT_MIN -=for apidoc AmnUh||PERL_UCHAR_MAX -=for apidoc AmnUh||PERL_UCHAR_MIN -=for apidoc AmnUh||PERL_UINT_MAX -=for apidoc AmnUh||PERL_ULONG_MAX -=for apidoc AmnUh||PERL_ULONG_MIN -=for apidoc AmnUh||PERL_UQUAD_MAX -=for apidoc AmnUh||PERL_UQUAD_MIN -=for apidoc AmnUh||PERL_USHORT_MAX -=for apidoc AmnUh||PERL_USHORT_MIN -=for apidoc AmnUh||PERL_QUAD_MIN +=for apidoc_section Integer configuration values + =for apidoc AmnU||PERL_INT_MAX -This and -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C, -C -give the largest and smallest number representable in the current +=for apidoc_item ||PERL_INT_MIN +=for apidoc_item ||PERL_LONG_MAX +=for apidoc_item ||PERL_LONG_MIN +=for apidoc_item ||PERL_SHORT_MAX +=for apidoc_item ||PERL_SHORT_MIN +=for apidoc_item ||PERL_UCHAR_MAX +=for apidoc_item ||PERL_UCHAR_MIN +=for apidoc_item ||PERL_UINT_MAX +=for apidoc_item ||PERL_UINT_MIN +=for apidoc_item ||PERL_ULONG_MAX +=for apidoc_item ||PERL_ULONG_MIN +=for apidoc_item ||PERL_USHORT_MAX +=for apidoc_item ||PERL_USHORT_MIN +=for apidoc_item ||PERL_QUAD_MAX +=for apidoc_item ||PERL_QUAD_MIN +=for apidoc_item ||PERL_UQUAD_MAX +=for apidoc_item ||PERL_UQUAD_MIN + +These give the largest and smallest number representable in the current platform in variables of the corresponding types. For signed types, the smallest representable number is the most negative @@ -2969,7 +3089,7 @@ typedef struct padname PADNAME; #endif /* -=head1 Miscellaneous Functions +=for apidoc_section Embedding and Interpreter Cloning =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv Provides system-specific tune up of the C runtime environment necessary to @@ -3526,11 +3646,8 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #define HEKfARG(p) ((void*)(p)) -/* -=for apidoc Amnh||UTF8f -=for apidoc Amh||UTF8fARG|bool is_utf8|Size_t byte_len|char *str - -=cut +/* Documented in perlguts + * * %4p is a custom format */ #ifndef UTF8f @@ -3569,14 +3686,14 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #endif /* -=head1 Miscellaneous Functions +=for apidoc_section Compiler directives -=for apidoc AmU|bool|LIKELY|const bool expr +=for apidoc Am||LIKELY|bool expr Returns the input unchanged, but at the same time it gives a branch prediction hint to the compiler that this condition is likely to be true. -=for apidoc AmU|bool|UNLIKELY|const bool expr +=for apidoc Am||UNLIKELY|bool expr Returns the input unchanged, but at the same time it gives a branch prediction hint to the compiler that this condition is likely to be false. @@ -3741,7 +3858,7 @@ typedef I32 (*filter_t) (pTHX_ int, SV *, int); && idx >= AvFILLp(PL_parser->rsfp_filters)) #define PERL_FILTER_EXISTS(i) \ (PL_parser && PL_parser->rsfp_filters \ - && (i) <= av_tindex(PL_parser->rsfp_filters)) + && (i) < av_count(PL_parser->rsfp_filters)) #if defined(_AIX) && !defined(_AIX43) #if defined(USE_REENTRANT) || defined(_REENTRANT) || defined(_THREAD_SAFE) @@ -4641,6 +4758,22 @@ EXTCONST char PL_No[] INIT(""); EXTCONST char PL_Zero[] INIT("0"); + +/* +=for apidoc_section Numeric Functions +=for apidoc AmTuU|const char *|PL_hexdigit|U8 value + +This array, indexed by an integer, converts that value into the character that +represents it. For example, if the input is 8, the return will be a string +whose first character is '8'. What is actually returned is a pointer into a +string. All you are interested in is the first character of that string. To +get uppercase letters (for the values 10..15), add 16 to the index. Hence, +C is C<'b'>, and C is C<'B'>. Adding 16 +to an index whose representation is '0'..'9' yields the same as not adding 16. +Indices outside the range 0..31 result in (bad) undedefined behavior. + +=cut +*/ EXTCONST char PL_hexdigit[] INIT("0123456789abcdef0123456789ABCDEF"); @@ -4713,7 +4846,7 @@ EXTCONST int PL_sig_num[]; # ifndef EBCDIC /* The EBCDIC fold table depends on the code page, and hence is found in - * utfebcdic.h */ + * ebcdic_tables.h */ EXTCONST unsigned char PL_fold[] = { 0, 1, 2, 3, 4, 5, 6, 7, @@ -5179,7 +5312,7 @@ typedef enum { #define HINT_RE_FLAGS 0x02000000 /* re '/xism' pragma */ -#define HINT_FEATURE_MASK 0x1c000000 /* 3 bits for feature bundles */ +#define HINT_FEATURE_MASK 0x3c000000 /* 4 bits for feature bundles */ /* Note: Used for HINT_M_VMSISH_*, currently defined by vms/vmsish.h: @@ -5444,8 +5577,14 @@ EXTCONST runops_proc_t PL_runops_dbg #define PERL_MAGIC_READONLY_ACCEPTABLE 0x40 #define PERL_MAGIC_VALUE_MAGIC 0x80 #define PERL_MAGIC_VTABLE_MASK 0x3F + +/* can this type of magic be attached to a readonly SV? */ #define PERL_MAGIC_TYPE_READONLY_ACCEPTABLE(t) \ (PL_magic_data[(U8)(t)] & PERL_MAGIC_READONLY_ACCEPTABLE) + +/* Is this type of magic container magic (%ENV, $1 etc), + * or value magic (pos, taint etc)? + */ #define PERL_MAGIC_TYPE_IS_VALUE_MAGIC(t) \ (PL_magic_data[(U8)(t)] & PERL_MAGIC_VALUE_MAGIC) @@ -6087,7 +6226,7 @@ typedef struct am_table_short AMTS; cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL)) /* -=head1 Locale-related functions and macros +=for apidoc_section Locales =for apidoc Amn|bool|IN_LOCALE @@ -6355,7 +6494,7 @@ the plain locale pragma without a parameter (S>) is in effect. * operations used by Perl, namely the decimal point, and even the thousands * separator.) -=head1 Locale-related functions and macros +=for apidoc_section Locales =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION @@ -6648,7 +6787,7 @@ cannot have changed since the precalculation. /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e @@ -6976,7 +7115,7 @@ EXTERN_C int flock(int fd, int op); #define IS_NUMBER_TRAILING 0x40 /* number has trailing trash */ /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send @@ -7084,10 +7223,19 @@ extern void moncontrol(int); #define PERL_UNICODE_WIDESYSCALLS 'W' #define PERL_UNICODE_UTF8CACHEASSERT 'a' +/* +=for apidoc_section Signals +=for apidoc Amn|U32|PERL_SIGNALS_UNSAFE_FLAG +If this bit in C is set, the system is uing the pre-Perl 5.8 +unsafe signals. See L and L. + +=cut +*/ #define PERL_SIGNALS_UNSAFE_FLAG 0x0001 /* -=head1 Numeric functions +=for apidoc_section Numeric Functions =for apidoc Am|int|PERL_ABS|int @@ -7119,7 +7267,7 @@ so no C. /* -=head1 Miscellaneous Functions +=for apidoc_section Utility Functions =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name