include/ws_attributes.h

   1 /* ws_attributes.h
   2  *
   3  * Wireshark - Network traffic analyzer
   4  * By Gerald Combs <gerald@wireshark.org>
   5  * Copyright 1998 Gerald Combs
   6  *
   7  * SPDX-License-Identifier: GPL-2.0-or-later
   8  */
   9
  10 #ifndef __WS_ATTRIBUTES_H__
  11 #define __WS_ATTRIBUTES_H__
  12
  13 #include "ws_compiler_tests.h"
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif /* __cplusplus */
  18
  19 /*
  20  * If we're running GCC or clang define _U_ to be "__attribute__((unused))"
  21  * so we can use _U_ to flag unused function parameters and not get warnings
  22  * about them. Otherwise, define _U_ to be an empty string so that _U_ used
  23  * to flag an unused function parameters will compile with other compilers.
  24  *
  25  * XXX - similar hints for other compilers?
  26  */
  27 #if defined(__GNUC__) || defined(__clang__)
  28   #define _U_ __attribute__((unused))
  29 #elif defined(_MSC_VER)
  30   #define _U_ __pragma(warning(suppress:4100 4189))
  31 #else
  32   #define _U_
  33 #endif
  34
  35 /*
  36  * WS_NORETURN, before a function declaration, means "this function
  37  * never returns".  (It must go before the function declaration, e.g.
  38  * "extern WS_NORETURN func(...)" rather than after the function
  39  * declaration, as the MSVC version has to go before the declaration.)
  40  */
  41 #ifndef __cplusplus
  42   #define WS_NORETURN _Noreturn
  43 #else /* __cplusplus */
  44 #if __has_attribute(noreturn) \
  45     || WS_IS_AT_LEAST_GNUC_VERSION(2,5) \
  46     || WS_IS_AT_LEAST_SUNC_VERSION(5,9) \
  47     || WS_IS_AT_LEAST_XL_C_VERSION(10,1) \
  48     || WS_IS_AT_LEAST_HP_C_VERSION(6,10)
  49   /*
  50    * Compiler with support for __attribute__((noreturn)), or GCC 2.5 and
  51    * later, or Solaris Studio 12 (Sun C 5.9) and later, or IBM XL C 10.1
  52    * and later (do any earlier versions of XL C support this?), or
  53    * HP aCC A.06.10 and later.
  54    */
  55   #define WS_NORETURN __attribute__((noreturn))
  56 #elif defined(_MSC_VER)
  57   /*
  58    * MSVC.
  59    */
  60   #define WS_NORETURN __declspec(noreturn)
  61 #else
  62   #define WS_NORETURN
  63 #endif
  64 #endif /* __cplusplus */
  65
  66 /*
  67  * WS_RETNONNULL, before a function declaration, means "this function
  68  * always returns a non-null pointer".
  69  */
  70 #if __has_attribute(returns_nonnull) \
  71     || WS_IS_AT_LEAST_GNUC_VERSION(4,9)
  72   #define WS_RETNONNULL __attribute__((returns_nonnull))
  73 #else
  74   #define WS_RETNONNULL
  75 #endif
  76
  77 /*
  78  * WS_DEPRECATED, before a function declaration, means "this function
  79  * should not be used anymore and will be removed in a future version".
  80  * WS_DEPRECATED_X() optionally takes a message saying what should be done
  81  * instead (strongly recommended).
  82  *
  83  * This is not implemented on purpose with MSVC because that compiler has no
  84  * equivalent to -Wno-error=deprecated-declarations, making it impossible
  85  * to build with -Werror and deprecated declarations. The Microsoft developer
  86  * team seems to not understand the requirement.
  87  * https://developercommunity.visualstudio.com/t/cant-treat-deprecated-warning-as-warning-with-wx/786502
  88  * https://developercommunity.visualstudio.com/t/impossible-to-treat-warning-as-error-except-specif/473936
  89  */
  90 #if __has_attribute(deprecated)
  91   #define WS_DEPRECATED         __attribute__((deprecated))
  92   #define WS_DEPRECATED_X(msg)  __attribute__((deprecated(msg)))
  93 #else
  94   #define WS_DEPRECATED
  95   #define WS_DEPRECATED_X(msg)
  96 #endif
  97
  98 /*
  99  * WS_THREAD_LOCAL means "this variable should go in thread-local
 100  * storage.
 101  *
 102  * Based on
 103  *
 104  *   https://en.wikipedia.org/w/index.php?title=Thread-local_storage&oldid=1064900318#C_and_C++
 105  *
 106  * the major UN*X C compilers support __thread and the major Windows C
 107  * compilers support __declspec(thread).
 108  */
 109 #ifdef _MSC_VER
 110   #define WS_THREAD_LOCAL __declspec(thread)
 111 #else
 112   #define WS_THREAD_LOCAL __thread
 113 #endif
 114
 115 /*
 116  * The warn_unused_result attribute causes a warning to be emitted if a caller
 117  * of the function with this attribute does not use its return value. This is
 118  * useful for functions where not checking the result is either a security
 119  * problem or always a bug, such as realloc.
 120  */
 121 #if defined(__GNUC__) || defined(__clang__)
 122   #define WS_WARN_UNUSED __attribute__((warn_unused_result))
 123 #else
 124   #define WS_WARN_UNUSED
 125 #endif
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif /* __cplusplus */
 130
 131 #endif /* __WS_ATTRIBUTES_H__ */