lib/noreturn.h

   1 /* Macros for declaring functions as non-returning.
   2
   3    Copyright (C) 2017-2024 Free Software Foundation, Inc.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation; either version 2.1 of the
   8    License, or (at your option) any later version.
   9
  10    This file is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 /* Written by Paul Eggert and Bruno Haible.  */
  19
  20 #ifndef _NORETURN_H
  21 #define _NORETURN_H 1
  22
  23 /* A "non-returning" function is a function which cannot return normally.
  24    It can transfer control only through longjmp(), throw (in C++), or similar
  25    mechanisms.
  26
  27    This file defines two macros _GL_NORETURN_FUNC and _GL_NORETURN_FUNCPTR,
  28    that declare a function to be non-returning.
  29    _GL_NORETURN_FUNC is for use in function declarations and function
  30    definitions.
  31    _GL_NORETURN_FUNCPTR is for use on function pointers.
  32
  33    Comparison of this file with <stdnoreturn.h>:
  34    <stdnoreturn.h> defines a macro (or keyword) _Noreturn that declares
  35    a function to be non-returning.  _Noreturn is only for use in function
  36    declarations and function definitions.
  37    Therefore, if the non-returning functions you have to declare are unlikely
  38    to be accessed through function pointers, and if the efficiency with C++
  39    compilers other than g++, clang, MSVC++ is not an issue to you, you can use
  40    module 'stdnoreturn' instead of this one, and _Noreturn instead of
  41    _GL_NORETURN_FUNC.
  42  */
  43
  44 /* Declares that a function is nonreturning.
  45    Use in C only code:
  46      _GL_NORETURN_FUNC extern void func (void);
  47      extern _GL_NORETURN_FUNC void func (void);
  48      extern void _GL_NORETURN_FUNC func (void);
  49    Use in C++ only code for a function with C linkage:
  50      extern "C" { _GL_NORETURN_FUNC void func (void); }
  51    Use in C++ only code for a function with C++ linkage:
  52      _GL_NORETURN_FUNC extern void func (void);
  53    Use in C & C++ code for a function with C linkage:
  54      #ifdef __cplusplus
  55      extern "C" {
  56      #endif
  57      _GL_NORETURN_FUNC void func (void);
  58      #ifdef __cplusplus
  59      }
  60      #endif
  61    Use in C & C++ code for a function with current language linkage:
  62      _GL_NORETURN_FUNC extern void func (void);
  63  */
  64 #if (3 <= __GNUC__ || (__GNUC__ == 2 && 8 <= __GNUC_MINOR__)) \
  65     || defined __clang__ \
  66     || (0x5110 <= __SUNPRO_C)
  67   /* For compatibility with _GL_NORETURN_FUNCPTR on clang, use
  68      __attribute__((__noreturn__)), not _Noreturn.  */
  69 # define _GL_NORETURN_FUNC __attribute__ ((__noreturn__))
  70 #elif 1200 <= _MSC_VER
  71   /* Use MSVC specific syntax.  */
  72 # define _GL_NORETURN_FUNC __declspec (noreturn)
  73 #elif defined __cplusplus
  74   /* Use ISO C++11 syntax when the compiler supports it.  */
  75 # if (__cplusplus >= 201103 && !(__GNUC__ == 4 && __GNUC_MINOR__ == 7)) \
  76      || (_MSC_VER >= 1900)
  77 #  define _GL_NORETURN_FUNC [[noreturn]]
  78   /* clang++ supports the _Noreturn keyword, but g++ doesn't.  */
  79 # elif defined __clang__
  80 #  define _GL_NORETURN_FUNC _Noreturn
  81 # else
  82 #  define _GL_NORETURN_FUNC /* empty */
  83 # endif
  84 #else
  85   /* Use ISO C11 syntax when the compiler supports it.  */
  86 # if __STDC_VERSION__ >= 201112 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 7)
  87 #  define _GL_NORETURN_FUNC _Noreturn
  88 # else
  89 #  define _GL_NORETURN_FUNC /* empty */
  90 # endif
  91 #endif
  92
  93 /* Declares that a function is nonreturning.
  94    Use in types and declarations that involve function pointers:
  95      _GL_NORETURN_FUNCPTR void (*funcptr) (void);
  96  */
  97 #if (3 <= __GNUC__ || (__GNUC__ == 2 && 8 <= __GNUC_MINOR__)) \
  98     || defined __clang__ \
  99     || (0x5110 <= __SUNPRO_C)
 100 # define _GL_NORETURN_FUNCPTR __attribute__ ((__noreturn__))
 101 #else
 102 # define _GL_NORETURN_FUNCPTR /* empty */
 103 #endif
 104
 105 /* Comments about the compiler dependent language features:
 106    - '_Noreturn'    - standardized by ISO C11, available in C only (not in C++),
 107                       and not applicable to pointers.
 108    - '[[noreturn]]' - standardized by ISO C++11, available in C++ only,
 109                       and not applicable to pointers.
 110    - '__attribute__((__noreturn__))' - available in GCC and clang only,
 111                                        both in C and C++.
 112    - '__declspec(noreturn)' - available in MSVC only,
 113                               both in C and C++, not applicable to pointers.
 114  */
 115
 116 #endif /* _NORETURN_H */