X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/41bd5b1176b48bff6dc0491197429c580c47263d..d78a5caa85b65d42bbf69df8d66aca78bcfdc3cf:/perl.h diff --git a/perl.h b/perl.h index f5f18ff..4a98718 100644 --- a/perl.h +++ b/perl.h @@ -1264,6 +1264,38 @@ EXTERN_C char *crypt(const char *, const char *); EXTERN_C char *crypt(const char *, const char *); #endif +/* +=head1 Errno + +=for apidoc m|void|SETERRNO|int errcode|int vmserrcode + +Set C, and on VMS set C. + +=for apidoc mn|void|dSAVEDERRNO + +Declare variables needed to save C and any operating system +specific error number. + +=for apidoc mn|void|dSAVE_ERRNO + +Declare variables needed to save C and any operating system +specific error number, and save them for optional later restoration +by C. + +=for apidoc mn|void|SAVE_ERRNO + +Save C and any operating system specific error number for +optional later restoration by C. Requires +C or C in scope. + +=for apidoc mn|void|RESTORE_ERRNO + +Restore C and any operating system specific error number that +was saved by C or C. + +=cut +*/ + #ifdef SETERRNO # undef SETERRNO /* SOCKS might have defined this */ #endif @@ -1335,6 +1367,29 @@ EXTERN_C char *crypt(const char *, const char *); # define RESTORE_ERRNO (errno = saved_errno) #endif +/* +=head1 Warning and Dieing + +=for apidoc Amn|SV *|ERRSV + +Returns the SV for C<$@>, creating it if needed. + +=for apidoc Am|void|CLEAR_ERRSV + +Clear the contents of C<$@>, setting it to the empty string. + +This replaces any read-only SV with a fresh SV and removes any magic. + +=for apidoc Am|void|SANE_ERRSV + +Clean up ERRSV so we can safely set it. + +This replaces any read-only SV with a fresh writable copy and removes +any magic. + +=cut +*/ + #define ERRSV GvSVn(PL_errgv) /* contains inlined gv_add_by_type */ @@ -1355,6 +1410,23 @@ EXTERN_C char *crypt(const char *, const char *); } \ } STMT_END +/* contains inlined gv_add_by_type */ +#define SANE_ERRSV() STMT_START { \ + SV ** const svp = &GvSV(PL_errgv); \ + if (!*svp) { \ + *svp = newSVpvs(""); \ + } else if (SvREADONLY(*svp)) { \ + SV *dupsv = newSVsv(*svp); \ + SvREFCNT_dec_NN(*svp); \ + *svp = dupsv; \ + } else { \ + SV *const errsv = *svp; \ + if (SvMAGICAL(errsv)) { \ + mg_free(errsv); \ + } \ + } \ + } STMT_END + #ifdef PERL_CORE # define DEFSV (0 + GvSVn(PL_defgv)) @@ -1580,9 +1652,17 @@ EXTERN_C char *crypt(const char *, const char *); /* This used to be conditionally defined based on whether we had a sprintf() * that correctly returns the string length (as required by C89), but we no * 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. But we no longer document it - * either (because using sprintf() rather than snprintf() is almost always - * a bad idea). */ + * a part of the API that's visible to modules. + +=head1 Miscellaneous Functions + +=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 +my_snprintf() + +=cut +*/ #define my_sprintf sprintf /* @@ -2402,6 +2482,58 @@ extern long double Perl_my_frexpl(long double x, int *e); # define PERL_QUAD_MIN (-PERL_QUAD_MAX - ((3 & -1) == 3)) #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 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 +platform in variables of the corresponding types. + +For signed types, the smallest representable number is the most negative +number, the one furthest away from zero. + +For C99 and later compilers, these correspond to things like C, which +are available to the C code. But these constants, furnished by Perl, +allow code compiled on earlier compilers to portably have access to the same +constants. + +=cut + +*/ + typedef MEM_SIZE STRLEN; typedef struct op OP; @@ -3434,8 +3566,25 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex) #else # define EXPECT(expr,val) (expr) #endif + +/* +=head1 Miscellaneous Functions + +=for apidoc AmU|bool|LIKELY|const 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 + +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. + +=cut +*/ #define LIKELY(cond) EXPECT(cBOOL(cond),TRUE) #define UNLIKELY(cond) EXPECT(cBOOL(cond),FALSE) + #ifdef HAS_BUILTIN_CHOOSE_EXPR /* placeholder */ #endif @@ -6036,6 +6185,27 @@ typedef struct am_table_short AMTS; # define IN_SOME_LOCALE_FORM_COMPILETIME \ cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL)) +/* +=head1 Locale-related functions and macros + +=for apidoc Amn|bool|IN_LOCALE + +Evaluates to TRUE if the plain locale pragma without a parameter (S>) is in effect. + +=for apidoc Amn|bool|IN_LOCALE_COMPILETIME + +Evaluates to TRUE if, when compiling a perl program (including an C) if +the plain locale pragma without a parameter (S>) is in effect. + +=for apidoc Amn|bool|IN_LOCALE_RUNTIME + +Evaluates to TRUE if, when executing a perl program (including an C) if +the plain locale pragma without a parameter (S>) is in effect. + +=cut +*/ + # define IN_LOCALE \ (IN_PERL_COMPILETIME ? IN_LOCALE_COMPILETIME : IN_LOCALE_RUNTIME) # define IN_SOME_LOCALE_FORM \ @@ -6357,7 +6527,15 @@ argument list, like this: On threaded perls not operating with thread-safe functionality, this macro uses a mutex to force a critical section. Therefore the matching RESTORE should be -close by, and guaranteed to be called. +close by, and guaranteed to be called; see L +for a more contained way to ensure that. + +=for apidoc Am|void|STORE_LC_NUMERIC_SET_TO_NEEDED_IN|bool in_lc_numeric + +Same as L with in_lc_numeric provided +as the precalculated value of C. It is the caller's +responsibility to ensure that the status of C and C +cannot have changed since the precalculation. =for apidoc Am|void|RESTORE_LC_NUMERIC @@ -6378,6 +6556,36 @@ expression, but with an empty argument list, like this: ... } +=for apidoc Am|void|WITH_LC_NUMERIC_SET_TO_NEEDED + +This macro invokes the supplied statement or block within the context +of a L .. L pair +if required, so eg: + + WITH_LC_NUMERIC_SET_TO_NEEDED( + SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis) + ); + +is equivalent to: + + { +#ifdef USE_LOCALE_NUMERIC + DECLARATION_FOR_LC_NUMERIC_MANIPULATION; + STORE_LC_NUMERIC_SET_TO_NEEDED(); +#endif + SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis); +#ifdef USE_LOCALE_NUMERIC + RESTORE_LC_NUMERIC(); +#endif + } + +=for apidoc Am|void|WITH_LC_NUMERIC_SET_TO_NEEDED_IN|bool in_lc_numeric + +Same as L with in_lc_numeric provided +as the precalculated value of C. It is the caller's +responsibility to ensure that the status of C and C +cannot have changed since the precalculation. + =cut */ @@ -6405,12 +6613,13 @@ expression, but with an empty argument list, like this: # define DECLARATION_FOR_LC_NUMERIC_MANIPULATION \ void (*_restore_LC_NUMERIC_function)(pTHX) = NULL -# define STORE_LC_NUMERIC_SET_TO_NEEDED() \ +# define STORE_LC_NUMERIC_SET_TO_NEEDED_IN(in) \ STMT_START { \ + bool _in_lc_numeric = (in); \ LC_NUMERIC_LOCK( \ - ( ( IN_LC(LC_NUMERIC) && _NOT_IN_NUMERIC_UNDERLYING) \ - || (! IN_LC(LC_NUMERIC) && _NOT_IN_NUMERIC_STANDARD)));\ - if (IN_LC(LC_NUMERIC)) { \ + ( ( _in_lc_numeric && _NOT_IN_NUMERIC_UNDERLYING) \ + || (! _in_lc_numeric && _NOT_IN_NUMERIC_STANDARD))); \ + if (_in_lc_numeric) { \ if (_NOT_IN_NUMERIC_UNDERLYING) { \ Perl_set_numeric_underlying(aTHX); \ _restore_LC_NUMERIC_function \ @@ -6426,6 +6635,9 @@ expression, but with an empty argument list, like this: } \ } STMT_END +# define STORE_LC_NUMERIC_SET_TO_NEEDED() \ + STORE_LC_NUMERIC_SET_TO_NEEDED_IN(IN_LC(LC_NUMERIC)) + # define RESTORE_LC_NUMERIC() \ STMT_START { \ if (_restore_LC_NUMERIC_function) { \ @@ -6500,6 +6712,17 @@ expression, but with an empty argument list, like this: __FILE__, __LINE__, PL_numeric_standard)); \ } STMT_END +# define WITH_LC_NUMERIC_SET_TO_NEEDED_IN(in_lc_numeric, block) \ + STMT_START { \ + DECLARATION_FOR_LC_NUMERIC_MANIPULATION; \ + STORE_LC_NUMERIC_SET_TO_NEEDED_IN(in_lc_numeric); \ + block; \ + RESTORE_LC_NUMERIC(); \ + } STMT_END; + +# define WITH_LC_NUMERIC_SET_TO_NEEDED(block) \ + WITH_LC_NUMERIC_SET_TO_NEEDED_IN(IN_LC(LC_NUMERIC), block) + #else /* !USE_LOCALE_NUMERIC */ # define SET_NUMERIC_STANDARD() @@ -6508,14 +6731,46 @@ expression, but with an empty argument list, like this: # define DECLARATION_FOR_LC_NUMERIC_MANIPULATION # define STORE_LC_NUMERIC_SET_STANDARD() # define STORE_LC_NUMERIC_FORCE_TO_UNDERLYING() +# define STORE_LC_NUMERIC_SET_TO_NEEDED_IN(in_lc_numeric) # define STORE_LC_NUMERIC_SET_TO_NEEDED() # define RESTORE_LC_NUMERIC() # define LOCK_LC_NUMERIC_STANDARD() # define UNLOCK_LC_NUMERIC_STANDARD() +# define WITH_LC_NUMERIC_SET_TO_NEEDED_IN(in_lc_numeric, block) \ + STMT_START { block; } STMT_END +# define WITH_LC_NUMERIC_SET_TO_NEEDED(block) \ + STMT_START { block; } STMT_END #endif /* !USE_LOCALE_NUMERIC */ #define Atof my_atof + +/* + +=head1 Numeric functions + +=for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e + +This is a synonym for L. + +=for apidoc AmTR|NV|Strtol|NN const char * const s|NULLOK char ** e|int base + +Platform and configuration independent C. This expands to the +appropriate C-like function based on the platform and F +options>. For example it could expand to C or C instead of +C. + +=for apidoc AmTR|NV|Strtoul|NN const char * const s|NULLOK char ** e|int base + +Platform and configuration independent C. This expands to the +appropriate C-like function based on the platform and F +options>. For example it could expand to C or C instead of +C. + +=cut + +*/ + #define Strtod my_strtod #if defined(HAS_STRTOD) \ @@ -6817,6 +7072,15 @@ int flock(int fd, int op); #define IS_NUMBER_NAN 0x20 /* this is not */ #define IS_NUMBER_TRAILING 0x40 /* number has trailing trash */ +/* +=head1 Numeric functions + +=for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send + +A synonym for L + +=cut +*/ #define GROK_NUMERIC_RADIX(sp, send) grok_numeric_radix(sp, send) /* Input flags: */ @@ -6897,8 +7161,20 @@ extern void moncontrol(int); #define PERL_SIGNALS_UNSAFE_FLAG 0x0001 -/* Use instead of abs() since abs() forces its argument to be an int, - * but also beware since this evaluates its argument twice, so no x++. */ +/* +=head1 Numeric functions + +=for apidoc Am|int|PERL_ABS|int + +Typeless C or C, I. (The usage below indicates it is for +integers, but it works for any type.) Use instead of these, since the C +library ones force their argument to be what it is expecting, potentially +leading to disaster. But also beware that this evaluates its argument twice, +so no C. + +=cut +*/ + #define PERL_ABS(x) ((x) < 0 ? -(x) : (x)) #if defined(__DECC) && defined(__osf__)