doc/noreturn.texi

   1 @c GNU noreturn, stdnoreturn modules documentation
   2
   3 @c Copyright (C) 2019--2024 Free Software Foundation, Inc.
   4
   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>.
  10
  11 @node Non-returning Functions
  12 @section Non-returning Functions
  13
  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 Instead of returning, it can loop forever, or it can transfer control via
  19 @code{abort}, @code{execvp}, @code{exit}, @code{longjmp}, @code{throw}
  20 (in C++), or similar mechanisms.  Non-returning functions are
  21 declared with a @code{void} return type.
  22
  23 It helps the compiler's ability to emit sensible warnings, following
  24 data-flow analysis, to declare which functions are non-returning.
  25 It can also help generate more-efficient code, as there is no need
  26 to save a return address when calling a non-returning function.
  27
  28 Gnulib has multiple ways to support such a declaration:
  29
  30 @itemize @bullet
  31 @item
  32 The @code{_Noreturn} keyword.  No modules are needed, as Gnulib
  33 arranges for @code{<config.h>} to define @code{_Noreturn} to an
  34 appropriate replacement on platforms lacking it.
  35 Unfortunately, although this approach works for all current C versions,
  36 the @code{_Noreturn} keyword is obsolescent in C23.
  37
  38 @item
  39 The @samp{noreturn} module.  It provides a way to put this declaration
  40 at function declarations, at function definitions, and in function
  41 pointer types.  The identifiers to use are:
  42 @itemize -
  43 @item
  44 @code{_GL_NORETURN_FUNC} for use in function declarations and function
  45 definitions.
  46 @item
  47 @code{_GL_NORETURN_FUNCPTR} for use on function pointers.
  48 @end itemize
  49 @noindent
  50 The include file is @code{<noreturn.h>}.
  51 @end itemize
  52
  53 Which of the approaches to use?  If the non-returning functions you
  54 have to declare are unlikely to be accessed through function pointers,
  55 you should use @code{_Noreturn}; otherwise the module
  56 @code{noreturn} provides for better data-flow analysis and thus for
  57 better warnings.
  58
  59 There is also an obsolete @code{stdnoreturn} module, but its use is no
  60 longer recommended.