X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/23f5c29f15e3fdadcf23a3ae28f3fc0bd738fd88..1d210779fca4e1f38a05cc35fab98b7584f54f27:/perl.h diff --git a/perl.h b/perl.h index e663311..70112bd 100644 --- a/perl.h +++ b/perl.h @@ -84,7 +84,7 @@ /* <--- here ends the logic shared by perl.h and makedef.pl */ /* -=for apidoc_section Compiler directives +=for apidoc_section $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 @@ -114,9 +114,9 @@ Otherwise ends a section of code already begun by a C>. #undef END_EXTERN_C #undef EXTERN_C #ifdef __cplusplus -# define START_EXTERN_C extern "C" { -# define END_EXTERN_C } # define EXTERN_C extern "C" +# define START_EXTERN_C EXTERN_C { +# define END_EXTERN_C } #else # define START_EXTERN_C # define END_EXTERN_C @@ -135,9 +135,6 @@ Otherwise ends a section of code already begun by a C>. # endif #endif -/* this used to be off by default, now its on, see perlio.h */ -#define PERLIO_FUNCS_CONST - #ifdef PERL_IMPLICIT_CONTEXT # ifndef MULTIPLICITY # define MULTIPLICITY @@ -183,7 +180,7 @@ Otherwise ends a section of code already begun by a C>. * * The only one Devel::PPPort handles is this; list it as deprecated -=for apidoc_section Concurrency +=for apidoc_section $concurrency =for apidoc AmD|void|CPERLscope|void x Now a no-op. @@ -406,7 +403,7 @@ Now a no-op. * 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_section $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 @@ -592,6 +589,18 @@ __typeof__ and nothing else. #define MSVC_DIAG_IGNORE_STMT(x) MSVC_DIAG_IGNORE(x) NOOP #define MSVC_DIAG_RESTORE_STMT MSVC_DIAG_RESTORE NOOP +/* +=for apidoc Amns||NOOP +Do nothing; typically used as a placeholder to replace something that used to +do something. + +=for apidoc Amns||dNOOP +Declare nothing; typically used as a placeholder to replace something that used +to declare something. Works on compilers that require declarations before any +code. + +=cut +*/ #define NOOP /*EMPTY*/(void)0 #define dNOOP struct Perl___notused_struct @@ -618,20 +627,29 @@ __typeof__ and nothing else. # define pTHX_12 12 #endif +/* +=for apidoc_section $concurrency +=for apidoc AmnU||dVAR +This is now a synonym for dNOOP: declare nothing + +=cut +*/ + #ifndef PERL_CORE -/* Backwards compatibility macro for XS code. It used to be part of - * the PERL_GLOBAL_STRUCT(_PRIVATE) feature, which no longer exists */ + /* Backwards compatibility macro for XS code. It used to be part of the + * PERL_GLOBAL_STRUCT(_PRIVATE) feature, which no longer exists */ # define dVAR dNOOP -#endif -/* these are only defined for compatibility; should not be used internally */ -#if !defined(pTHXo) && !defined(PERL_CORE) -# define pTHXo pTHX -# define pTHXo_ pTHX_ -# define aTHXo aTHX -# define aTHXo_ aTHX_ -# define dTHXo dTHX -# define dTHXoa(x) dTHXa(x) + /* these are only defined for compatibility; should not be used internally. + * */ +# ifndef pTHXo +# define pTHXo pTHX +# define pTHXo_ pTHX_ +# define aTHXo aTHX +# define aTHXo_ aTHX_ +# define dTHXo dTHX +# define dTHXoa(x) dTHXa(x) +# endif #endif #ifndef pTHXx @@ -658,7 +676,7 @@ __typeof__ and nothing else. #endif /* -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc AmnUu|void|STMT_START =for apidoc_item ||STMT_END @@ -1047,7 +1065,7 @@ EXTERN_C int usleep(unsigned int); /* Macros for correct constant construction. These are in C99 * (so they will not be available in strict C89 mode), but they are nice, so * let's define them if necessary. -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc Am|I16|INT16_C|number =for apidoc_item |I32|INT32_C|number =for apidoc_item |I64|INT64_C|number @@ -1137,7 +1155,7 @@ Use C> to get the largest type available on the platform. # endif /* -=for apidoc_section Integer configuration values +=for apidoc_section $integer =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 C or C. #endif /* -=for apidoc_section Warning and Dieing +=for apidoc_section $warning =for apidoc Amn|SV *|ERRSV @@ -1655,7 +1673,7 @@ any magic. #endif /* -=for apidoc_section SV Handling +=for apidoc_section $SV =for apidoc Amn|SV *|DEFSV Returns the SV associated with C<$_> @@ -1877,7 +1895,7 @@ Localize C<$_>. See L. * 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. -=for apidoc_section String Handling +=for apidoc_section $string =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 @@ -2535,8 +2553,8 @@ extern long double Perl_my_frexpl(long double x, int *e); # define Perl_fp_class_snan(x) (_fpclass(x) & _FPCLASS_SNAN) # define Perl_fp_class_qnan(x) (_fpclass(x) & _FPCLASS_QNAN) # define Perl_fp_class_nan(x) (_fpclass(x) & (_FPCLASS_SNAN|_FPCLASS_QNAN)) -# define Perl_fp_class_ninf(x) (_fpclass(x) & _FPCLASS_NINF)) -# define Perl_fp_class_pinf(x) (_fpclass(x) & _FPCLASS_PINF)) +# define Perl_fp_class_ninf(x) (_fpclass(x) & _FPCLASS_NINF) +# define Perl_fp_class_pinf(x) (_fpclass(x) & _FPCLASS_PINF) # define Perl_fp_class_inf(x) (_fpclass(x) & (_FPCLASS_NINF|_FPCLASS_PINF)) # define Perl_fp_class_nnorm(x) (_fpclass(x) & _FPCLASS_NN) # define Perl_fp_class_pnorm(x) (_fpclass(x) & _FPCLASS_PN) @@ -2664,6 +2682,41 @@ extern long double Perl_my_frexpl(long double x, int *e); #define my_atof2(a,b) my_atof3(a,b,0) /* +=for apidoc_section $numeric +=for apidoc AmT|NV|Perl_acos|NV x +=for apidoc_item |NV|Perl_asin|NV x +=for apidoc_item |NV|Perl_atan|NV x +=for apidoc_item |NV|Perl_atan2|NV x|NV y +=for apidoc_item |NV|Perl_ceil|NV x +=for apidoc_item |NV|Perl_cos|NV x +=for apidoc_item |NV|Perl_cosh|NV x +=for apidoc_item |NV|Perl_exp|NV x +=for apidoc_item |NV|Perl_floor|NV x +=for apidoc_item |NV|Perl_fmod|NV x|NV y +=for apidoc_item |NV|Perl_frexp|NV x|int *exp +=for apidoc_item |IV|Perl_isfinite|NV x +=for apidoc_item |IV|Perl_isinf|NV x +=for apidoc_item |IV|Perl_isnan|NV x +=for apidoc_item |NV|Perl_ldexp|NV x|int exp +=for apidoc_item |NV|Perl_log|NV x +=for apidoc_item |NV|Perl_log10|NV x +=for apidoc_item |NV|Perl_modf|NV x|NV *iptr +=for apidoc_item |NV|Perl_pow|NV x|NV y +=for apidoc_item |NV|Perl_sin|NV x +=for apidoc_item |NV|Perl_sinh|NV x +=for apidoc_item |NV|Perl_sqrt|NV x +=for apidoc_item |NV|Perl_tan|NV x +=for apidoc_item |NV|Perl_tanh|NV x + +These perform the corresponding mathematical operation on the operand(s), using +the libc function designed for the task that has just enough precision for an +NV on this platform. If no such function with sufficient precision exists, +the highest precision one available is used. + +=cut +*/ + +/* * CHAR_MIN and CHAR_MAX are not included here, as the (char) type may be * ambiguous. It may be equivalent to (signed char) or (unsigned char) * depending on local options. Until Configure detects this (or at least @@ -2701,7 +2754,7 @@ extern long double Perl_my_frexpl(long double x, int *e); #endif /* -=for apidoc_section Integer configuration values +=for apidoc_section $integer =for apidoc AmnU||PERL_INT_MAX =for apidoc_item ||PERL_INT_MIN @@ -2779,6 +2832,7 @@ typedef struct gv GV; typedef struct io IO; typedef struct context PERL_CONTEXT; typedef struct block BLOCK; +typedef struct invlist INVLIST; typedef struct magic MAGIC; typedef struct xpv XPV; @@ -3121,7 +3175,7 @@ typedef struct padname PADNAME; #endif /* -=for apidoc_section Embedding and Interpreter Cloning +=for apidoc_section $embedding =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv Provides system-specific tune up of the C runtime environment necessary to @@ -3718,7 +3772,7 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #endif /* -=for apidoc_section Compiler directives +=for apidoc_section $directives =for apidoc Am||LIKELY|bool expr @@ -3781,40 +3835,55 @@ hint to the compiler that this condition is likely to be false. # define __has_builtin(x) 0 /* not a clang style compiler */ #endif -/* ASSUME is like assert(), but it has a benefit in a release build. It is a - hint to a compiler about a statement of fact in a function call free - expression, which allows the compiler to generate better machine code. - In a debug build, ASSUME(x) is a synonym for assert(x). ASSUME(0) means - the control path is unreachable. In a for loop, ASSUME can be used to hint - that a loop will run at least X times. ASSUME is based off MSVC's __assume - intrinsic function, see its documents for more details. +/* +=for apidoc Am||ASSUME|bool expr +C is like C, but it has a benefit in a release build. It is a +hint to a compiler about a statement of fact in a function call free +expression, which allows the compiler to generate better machine code. In a +debug build, C is a synonym for C. C means the +control path is unreachable. In a for loop, C can be used to hint that +a loop will run at least X times. C is based off MSVC's C<__assume> +intrinsic function, see its documents for more details. + +=cut */ -#ifndef DEBUGGING -# if __has_builtin(__builtin_unreachable) \ - || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5 || __GNUC__ > 4) /* 4.5 -> */ +#ifdef DEBUGGING +# define ASSUME(x) assert(x) +# if __has_builtin(__builtin_unreachable) +# define HAS_BUILTIN_UNREACHABLE +# elif (defined(__GNUC__) && ( __GNUC__ > 4 \ + || __GNUC__ == 4 && __GNUC_MINOR__ >= 5)) +# define HAS_BUILTIN_UNREACHABLE +# endif +#endif + +#if defined(__sun) || (defined(__hpux) && !defined(__GNUC__)) +# ifndef ASSUME +# define ASSUME(x) /* ASSUME() generates warnings on Solaris */ +# endif +# define NOT_REACHED +#elif defined(HAS_BUILTIN_UNREACHABLE) +# ifndef ASSUME # define ASSUME(x) ((x) ? (void) 0 : __builtin_unreachable()) -# elif defined(_MSC_VER) +# endif +# define NOT_REACHED \ + STMT_START { \ + ASSUME(!"UNREACHABLE"); __builtin_unreachable(); \ + } STMT_END +#else +# if defined(_MSC_VER) # define ASSUME(x) __assume(x) # elif defined(__ARMCC_VERSION) /* untested */ # define ASSUME(x) __promise(x) # else -/* a random compiler might define assert to its own special optimization token - so pass it through to C lib as a last resort */ + /* a random compiler might define assert to its own special optimization + * token so pass it through to C lib as a last resort */ # define ASSUME(x) assert(x) # endif -#else -# define ASSUME(x) assert(x) -#endif - -#if defined(__sun) /* ASSUME() generates warnings on Solaris */ -# define NOT_REACHED -#elif defined(DEBUGGING) && (__has_builtin(__builtin_unreachable) \ - || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5 || __GNUC__ > 4)) /* 4.5 -> */ -# define NOT_REACHED STMT_START { ASSUME(!"UNREACHABLE"); __builtin_unreachable(); } STMT_END -#else # define NOT_REACHED ASSUME(!"UNREACHABLE") #endif +#undef HAS_BUILTIN_UNREACHABLE /* Some unistd.h's give a prototype for pause() even though HAS_PAUSE ends up undefined. This causes the #define @@ -3910,7 +3979,7 @@ typedef struct crypt_data { /* straight from /usr/include/crypt.h */ #ifndef PERL_CALLCONV # ifdef __cplusplus -# define PERL_CALLCONV extern "C" +# define PERL_CALLCONV EXTERN_C # else # define PERL_CALLCONV # endif @@ -3925,8 +3994,9 @@ typedef struct crypt_data { /* straight from /usr/include/crypt.h */ #ifndef PERL_STATIC_NO_RET # define PERL_STATIC_NO_RET STATIC #endif -/* PERL_STATIC_NO_RET is supposed to be equivalent to PERL_STATIC_INLINE on - builds that dont have a noreturn as a declaration specifier + +/* PERL_STATIC_INLINE_NO_RET is supposed to be equivalent to PERL_STATIC_INLINE + * on builds that dont have a noreturn as a declaration specifier */ #ifndef PERL_STATIC_INLINE_NO_RET # define PERL_STATIC_INLINE_NO_RET PERL_STATIC_INLINE @@ -4153,7 +4223,7 @@ my_swap16(const U16 x) { out of range floating point values to integers *is* undefined behaviour, and it is starting to bite. -=for apidoc_section Casting +=for apidoc_section $casting =for apidoc Am|I32|I_32|NV what Cast an NV to I32 while avoiding undefined C behavior @@ -4192,6 +4262,25 @@ Cast an NV to UV while avoiding undefined C behavior #define U_I(what) ((unsigned int)U_32(what)) #define U_L(what) U_32(what) +/* +=for apidoc_section $integer +=for apidoc Amn|IV|IV_MAX +The largest signed integer that fits in an IV on this platform. + +=for apidoc Amn|IV|IV_MIN +The negative signed integer furthest away from 0 that fits in an IV on this +platform. + +=for apidoc Amn|UV|UV_MAX +The largest unsigned integer that fits in a UV on this platform. + +=for apidoc Amn|UV|UV_MIN +The smallest unsigned integer that fits in a UV on this platform. It should +equal zero. + +=cut +*/ + #ifdef HAS_SIGNBIT # ifndef Perl_signbit # define Perl_signbit signbit @@ -4808,7 +4897,7 @@ EXTCONST char PL_Zero[] INIT("0"); /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmTuU|const char *|PL_hexdigit|U8 value This array, indexed by an integer, converts that value into the character that @@ -6286,7 +6375,7 @@ typedef struct am_table_short AMTS; cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL)) /* -=for apidoc_section Locales +=for apidoc_section $locale =for apidoc Amn|bool|IN_LOCALE @@ -6554,7 +6643,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.) -=for apidoc_section Locales +=for apidoc_section $locale =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION @@ -6847,7 +6936,7 @@ cannot have changed since the precalculation. /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e @@ -7175,7 +7264,7 @@ EXTERN_C int flock(int fd, int op); #define IS_NUMBER_TRAILING 0x40 /* number has trailing trash */ /* -=for apidoc_section Numeric Functions +=for apidoc_section $numeric =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send @@ -7245,6 +7334,8 @@ extern void moncontrol(int); #define PERL_MAGIC_UTF8_CACHESIZE 2 +#ifdef PERL_CORE + #define PERL_UNICODE_STDIN_FLAG 0x0001 #define PERL_UNICODE_STDOUT_FLAG 0x0002 #define PERL_UNICODE_STDERR_FLAG 0x0004 @@ -7283,8 +7374,10 @@ extern void moncontrol(int); #define PERL_UNICODE_WIDESYSCALLS 'W' #define PERL_UNICODE_UTF8CACHEASSERT 'a' +#endif + /* -=for apidoc_section Signals +=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 and L or C, I. (The usage below indicates it is for integers, but it works for any type.) Use instead of these, since the C @@ -7327,7 +7420,7 @@ so no C. /* -=for apidoc_section Utility Functions +=for apidoc_section $utility =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name