lib/noreturn.h

   1 /* Macros for declaring functions as non-returning.
   2
   3    Copyright (C) 2017 Free Software Foundation, Inc.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program 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 General Public License for more details.
  14
  15    You should have received a copy of the GNU 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     || (0x5110 <= __SUNPRO_C)
  66   /* For compatibility with _GL_NORETURN_FUNCPTR on clang, use
  67      __attribute__((__noreturn__)), not _Noreturn.  */
  68 # define _GL_NORETURN_FUNC __attribute__ ((__noreturn__))
  69 #elif 1200 <= _MSC_VER
  70   /* Use MSVC specific syntax.  */
  71 # define _GL_NORETURN_FUNC __declspec (noreturn)
  72 #elif defined __cplusplus
  73   /* Use ISO C++11 syntax when the compiler supports it.  */
  74 # if (__cplusplus >= 201103 && !(__GNUC__ == 4 && __GNUC_MINOR__ == 7)) \
  75      || (_MSC_VER >= 1900)
  76 #  define _GL_NORETURN_FUNC [[noreturn]]
  77 # else
  78 #  define _GL_NORETURN_FUNC /* empty */
  79 # endif
  80 #else
  81   /* Use ISO C11 syntax when the compiler supports it.  */
  82 # if __STDC_VERSION__ >= 201112 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 7)
  83 #  define _GL_NORETURN_FUNC _Noreturn
  84 # else
  85 #  define _GL_NORETURN_FUNC /* empty */
  86 # endif
  87 #endif
  88
  89 /* Declares that a function is nonreturning.
  90    Use in types and declarations that involve function pointers:
  91      _GL_NORETURN_FUNCPTR void (*funcptr) (void);
  92  */
  93 #if (3 <= __GNUC__ || (__GNUC__ == 2 && 8 <= __GNUC_MINOR__)) \
  94     || (0x5110 <= __SUNPRO_C)
  95 # define _GL_NORETURN_FUNCPTR __attribute__ ((__noreturn__))
  96 #else
  97 # define _GL_NORETURN_FUNCPTR /* empty */
  98 #endif
  99
 100 /* Comments about the compiler dependent language features:
 101    - '_Noreturn'    - standardized by ISO C11, available in C only (not in C++),
 102                       and not applicable to pointers.
 103    - '[[noreturn]]' - standardized by ISO C++11, available in C++ only,
 104                       and not applicable to pointers.
 105    - '__attribute__((__noreturn__))' - available in GCC and clang only,
 106                                        both in C and C++.
 107    - '__declspec(noreturn)' - available in MSVC only,
 108                               both in C and C++, not applicable to pointers.
 109  */
 110
 111 #endif /* _NORETURN_H */