1 @c GNU noreturn, stdnoreturn modules documentation
3 @c Copyright (C) 2019--2021 Free Software Foundation, Inc.
5 @c Permission is granted to copy, distribute and/or modify this document
6 @c under the terms of the GNU Free Documentation License, Version 1.3 or
7 @c any later version published by the Free Software Foundation; with no
8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
9 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
11 @node Non-returning Functions
12 @section Non-returning Functions
14 @cindex @code{_Noreturn}
15 @cindex @code{noreturn}
16 @cindex @code{stdnoreturn}
17 A "non-returning" function is a function which cannot return normally.
18 It can transfer control only through @code{longjmp()}, @code{throw}
19 (in C++), or similar mechanisms. The most prominent function of this
20 class is the @code{abort} function. Non-returning functions are
21 declared with a @code{void} return type.
23 It helps the compiler's ability to emit sensible warnings, following
24 data-flow analysis, to declare which functions are non-returning.
26 To decorate function declarations and function definitions, you can
27 use the @code{_Noreturn} keyword. No modules are needed, as Gnulib
28 arranges for @code{<config.h>} to define @code{_Noreturn} to an
29 appropriate replacement on platforms lacking it.
31 Gnulib has two modules that support such a declaration:
35 The @samp{noreturn} module. It provides a way to put this declaration
36 at function declarations, at function definitions, and in function
37 pointer types. The identifiers to use are:
40 @code{_GL_NORETURN_FUNC} for use in function declarations and function
43 @code{_GL_NORETURN_FUNCPTR} for use on function pointers.
46 The include file is @code{<noreturn.h>}.
49 The @samp{stdnoreturn} module. This can improve readability by
50 letting you use @code{noreturn} instead of @code{_Noreturn};
51 unfortunately, @code{noreturn} is a no-op on some platforms even
52 though @code{_Noreturn} works on them. The include file is
53 @code{<stdnoreturn.h>}.
56 Which of the two modules to use? If the non-returning functions you
57 have to declare are unlikely to be accessed through function pointers,
58 you should use module @code{stdnoreturn}; otherwise the module
59 @code{noreturn} provides for better data-flow analysis and thus for
62 For a detailed description of the @code{stdnoreturn} module, see