Change docs display for PERL_UNUSED_foo

[perl5.git] / perl.h

diff --git a/perl.h b/perl.h
index 88d0511..4829578 100644 (file)
--- a/perl.h
+++ b/perl.h
@@ -83,6 +83,33 @@
 
 /* <--- here ends the logic shared by perl.h and makedef.pl */
 
 
 /* <--- 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<L</START_EXTERN_C>> ... C<L</END_EXTERN_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<L</EXTERN_C>> applied to it, that is to have external C linkage.  The
+section is ended by a C<L</END_EXTERN_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<L</START_EXTERN_C>>.
+
+=cut
+*/
+

 #undef START_EXTERN_C
 #undef END_EXTERN_C
 #undef EXTERN_C
 #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.
  * 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
  */
 #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).
  * 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<L</PERL_UNUSED_ARG>> 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
  */
 
 #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 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<x> 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))
  */
 #ifndef PERL_UNUSED_ARG
 #  define PERL_UNUSED_ARG(x) ((void)sizeof(x))


@@ -408,31 +479,40 @@
 #  endif
 #endif
 
 #  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<e.g.>,
+
+ PERL_UNUSED_RESULT(foo(a, b))
+
+The main reason for this is that the combination of C<gcc -Wunused-result>
+(part of C<-Wall>) and the C<__attribute__((warn_unused_result))> cannot
+be silenced with casting to C<void>.  This causes trouble when the system
+header files use the attribute.
+
+Use C<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, I<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 C<PERL_UNUSED_RESULT> might not be the most natural way:
+another possibility is that you can capture the return value
+and use C<L</PERL_UNUSED_VAR>> 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
 #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
 
 /*
 #endif
 
 /*

-=head1 Miscellaneous Functions
-
+=for apidoc_section Compiler directives

 =for apidoc AmnUu|void|STMT_START
 =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<L</PERL_USE_GCC_BRACE_GROUPS>>.

 
 

- 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<statements ...> into an expression with a
+value, unlike plain C language blocks.  This can present optimization
+possibilities, B<BUT> 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
 
 
 =cut
 


@@ -1011,6 +1112,25 @@ EXTERN_C int usleep(unsigned int);
 #    define UINT64_C(c) PeRl_UINT64_C(c)
 #  endif
 
 #    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<number> of the
+widest integer type on the machine.  For example, if the machine has C<long
+long>s, C<INTMAX_C(-1)> would yield
+
+ -1LL
+
+=for apidoc Am||UINTMAX_C|number
+Returns a token the C compiler recognizes for the constant C<number> of the
+widest unsigned integer type on the machine.  For example, if the machine has
+C<long>s, C<UINTMAX_C(1)> would yield
+
+ 1UL
+
+=cut
+*/
+

 #  ifndef I_STDINT
     typedef I64TYPE PERL_INTMAX_T;
     typedef U64TYPE PERL_UINTMAX_T;
 #  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
 
 /*
 #endif
 
 /*

-=head1 Errno
+=for apidoc_section Errno

 
 =for apidoc m|void|SETERRNO|int errcode|int vmserrcode
 
 
 =for apidoc m|void|SETERRNO|int errcode|int vmserrcode
 


@@ -1425,7 +1545,7 @@ was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>.
 #endif
 
 /*
 #endif
 
 /*

-=head1 Warning and Dieing
+=for apidoc_section Warning and Dieing

 
 =for apidoc Amn|SV *|ERRSV
 
 
 =for apidoc Amn|SV *|ERRSV
 


@@ -1502,6 +1622,20 @@ any magic.
 # define SAVE_DEFSV SAVESPTR(GvSV(PL_defgv))
 #endif
 
 # 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<sv> with C<$_>
+
+=for apidoc Amn|void|SAVE_DEFSV
+Localize C<$_>.  See L<perlguts/Localizing changes>.
+
+=cut
+*/
+

 #ifndef errno
        extern int errno;     /* ANSI allows errno to be an lvalue expr.
                               * For example in multithreaded environments
 #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.
 
  * 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<buffer>.  Instead use
 =for apidoc ATmD|int|my_sprintf|NN char *buffer|NN const char *pat|...
 
 Do NOT use this due to the possibility of overflowing C<buffer>.  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.
  *  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
  */
 #if (IVSIZE == PTRSIZE) && (UVSIZE == PTRSIZE)
 #  define PTRV                 UV


@@ -2534,43 +2669,28 @@ extern long double Perl_my_frexpl(long double x, int *e);
 #endif
 
 /*
 #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
 =for apidoc AmnU||PERL_INT_MAX

-This and
-C<PERL_INT_MIN>,
-C<PERL_LONG_MAX>,
-C<PERL_LONG_MIN>,
-C<PERL_QUAD_MAX>,
-C<PERL_SHORT_MAX>,
-C<PERL_SHORT_MIN>,
-C<PERL_UCHAR_MAX>,
-C<PERL_UCHAR_MIN>,
-C<PERL_UINT_MAX>,
-C<PERL_ULONG_MAX>,
-C<PERL_ULONG_MIN>,
-C<PERL_UQUAD_MAX>,
-C<PERL_UQUAD_MIN>,
-C<PERL_USHORT_MAX>,
-C<PERL_USHORT_MIN>,
-C<PERL_QUAD_MIN>
-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
 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
 
 /*
 #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
 
 =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))
 
 
 #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
  * %4p is a custom format
  */
 #ifndef UTF8f


@@ -3569,14 +3686,14 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex)
 #endif
 
 /*
 #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.
 
 
 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.
 
 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 \
                && 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)
 
 #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");
   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<PL_hexdigit[11]> is C<'b'>, and C<PL_hexdigit[11+16]> 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");
 
 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
 #  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,
 
 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_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:
 
                                /* 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
 #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)
 #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)
 
 #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))
 
 /*
                         cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL))
 
 /*

-=head1 Locale-related functions and macros
+=for apidoc_section Locales

 
 =for apidoc Amn|bool|IN_LOCALE
 
 
 =for apidoc Amn|bool|IN_LOCALE
 


@@ -6355,7 +6494,7 @@ the plain locale pragma without a parameter (S<C<use locale>>) is in effect.
  * operations used by Perl, namely the decimal point, and even the thousands
  * separator.)
 
  * 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
 
 
 =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
 
 
 =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 */
 
 /*
 #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
 
 
 =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'
 
 #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<PL_signals> is set, the system is uing the pre-Perl 5.8
+unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
+(Safe Signals)>.
+
+=cut
+*/

 #define PERL_SIGNALS_UNSAFE_FLAG       0x0001
 
 /*
 #define PERL_SIGNALS_UNSAFE_FLAG       0x0001
 
 /*

-=head1 Numeric functions
+=for apidoc_section Numeric Functions

 
 =for apidoc Am|int|PERL_ABS|int
 
 
 =for apidoc Am|int|PERL_ABS|int
 


@@ -7119,7 +7267,7 @@ so no C<x++>.
 
 
 /*
 
 
 /*

-=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
 
 
 =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name