Re: undefined behaviour findings in bitset

[Bruno Haible]

Akim Demaille wrote:
> Also, the relationship with noreturn.h is not completely clear for
> me either.

I'm adding this documentation:


2019-03-19  Bruno Haible  <address@hidden>

        doc: Document the 'stdnoreturn' and 'noreturn' modules.
        Reported by Akim Demaille.
        * doc/noreturn.texi: New file.
        * doc/gnulib.texi: Include it.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index ac3d570..838895c 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -6372,6 +6372,7 @@ to POSIX that it can be treated like any other Unix-like 
platform.
 * alloca-opt::
 * Safe Allocation Macros::
 * Compile-time Assertions::
+* Non-returning Functions::
 * Integer Properties::
 * static inline::
 * extern inline::
@@ -6402,6 +6403,8 @@ to POSIX that it can be treated like any other Unix-like 
platform.
 
 @include verify.texi
 
address@hidden noreturn.texi
+
 @include intprops.texi
 
 @include static-inline.texi
diff --git a/doc/noreturn.texi b/doc/noreturn.texi
new file mode 100644
index 0000000..862a409
--- /dev/null
+++ b/doc/noreturn.texi
@@ -0,0 +1,60 @@
address@hidden GNU noreturn, stdnoreturn modules documentation
+
address@hidden Copyright (C) 2019 Free Software Foundation, Inc.
+
address@hidden Permission is granted to copy, distribute and/or modify this 
document
address@hidden under the terms of the GNU Free Documentation License, Version 
1.3
address@hidden or any later version published by the Free Software Foundation;
address@hidden with no Invariant Sections, no Front-Cover Texts, and no 
Back-Cover
address@hidden Texts.  A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Non-returning Functions
address@hidden Non-returning Functions
+
address@hidden @code{_Noreturn}
address@hidden @code{noreturn}
address@hidden @code{stdnoreturn}
+A "non-returning" function is a function which cannot return normally.
+It can transfer control only through @code{longjmp()}, @code{throw}
+(in C++), or similar mechanisms.  The most prominent function of this
+class is the @code{abort} function.  Non-returning functions are
+declared with a @code{void} return type.
+
+It helps the compiler's ability to emit sensible warnings, following
+data-flow analysis, to declare which functions are non-returning.
+
+Gnulib has two modules that support such a declaration:
+
address@hidden @bullet
address@hidden
+The @samp{stdnoreturn} module.  It provides a way to put this
+declaration at function declarations and function definitions, but not
+in function pointer types.  The identifier to use is @code{_Noreturn}
+or @code{noreturn}; @code{_Noreturn} is to be preferred because
address@hidden is a no-op on some platforms.  The include file is
address@hidden<stdnoreturn.h>}.
+
address@hidden
+The @samp{noreturn} module.  It provides a way to put this declaration
+at function declarations, at function definitions, and in function
+pointer types.  The identifiers to use are:
address@hidden -
address@hidden
address@hidden for use in function declarations and function
+definitions.
address@hidden
address@hidden for use on function pointers.
address@hidden itemize
address@hidden
+The include file is @code{<noreturn.h>}.
address@hidden itemize
+
+Which of the two modules to use?  If the non-returning functions you
+have to declare are unlikely to be accessed through function pointers,
+you should use module @code{stdnoreturn}; otherwise the module
address@hidden provides for better data-flow analysis and thus for
+better warnings.
+
+For a detailed description of the @code{stdnoreturn} module, see
address@hidden