Non-returning Functions
=======================

A "non-returning" function is a function which cannot return normally. It can transfer control only through longjmp(), throw (in C++), or similar mechanisms.  The most prominent function of this class is the abort function.  Non-returning functions are declared with a 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:

  * The 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 _Noreturn or noreturn; _Noreturn is to be preferred because noreturn is a no-op on some platforms.  The include file is <stdnoreturn.h>.

  * The 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:

       - _GL_NORETURN_FUNC for use in function declarations and function definitions.

       - _GL_NORETURN_FUNCPTR for use on function pointers.

     The include file is <noreturn.h>.

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 stdnoreturn; otherwise the module noreturn provides for better data-flow analysis and thus for better warnings.

For a detailed description of the stdnoreturn module, see stdnoreturn.h.