AnnotationMacrosC.h (6435B)
1 /** @file 2 @brief Header containing macros for source-level annotation. 3 4 In theory, supporting MSVC SAL, as well as compatible GCC and 5 Clang attributes. In practice, expanded as time allows and requires. 6 7 Must be c-safe! 8 9 @date 2014 10 11 @author 12 Sensics, Inc. 13 <http://sensics.com/osvr> 14 */ 15 16 /* 17 // Copyright 2014 Sensics, Inc. 18 // 19 // Licensed under the Apache License, Version 2.0 (the "License"); 20 // you may not use this file except in compliance with the License. 21 // You may obtain a copy of the License at 22 // 23 // http://www.apache.org/licenses/LICENSE-2.0 24 // 25 // Unless required by applicable law or agreed to in writing, software 26 // distributed under the License is distributed on an "AS IS" BASIS, 27 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 28 // See the License for the specific language governing permissions and 29 // limitations under the License. 30 */ 31 32 #ifndef INCLUDED_AnnotationMacrosC_h_GUID_48538D9B_35E3_4E9A_D2B0_D83D51DD5900 33 #define INCLUDED_AnnotationMacrosC_h_GUID_48538D9B_35E3_4E9A_D2B0_D83D51DD5900 34 35 #ifndef OSVR_DISABLE_ANALYSIS 36 37 # if defined(_MSC_VER) && (_MSC_VER >= 1700) 38 /* Visual C++ (2012 and newer) */ 39 /* Using SAL attribute format: 40 * http://msdn.microsoft.com/en-us/library/ms182032(v=vs.120).aspx */ 41 42 # include <sal.h> 43 44 # define OSVR_IN _In_ 45 # define OSVR_IN_PTR _In_ 46 # define OSVR_IN_OPT _In_opt_ 47 # define OSVR_IN_STRZ _In_z_ 48 # define OSVR_IN_READS(NUM_ELEMENTS) _In_reads_(NUM_ELEMENTS) 49 50 # define OSVR_OUT _Out_ 51 # define OSVR_OUT_PTR _Outptr_ 52 # define OSVR_OUT_OPT _Out_opt_ 53 54 # define OSVR_INOUT _Inout_ 55 # define OSVR_INOUT_PTR _Inout_ 56 57 # define OSVR_RETURN_WARN_UNUSED _Must_inspect_result_ 58 # define OSVR_RETURN_SUCCESS_CONDITION(X) _Return_type_success_(X) 59 60 /* end of msvc section */ 61 # elif defined(__GNUC__) && (__GNUC__ >= 4) 62 /* section for GCC and GCC-alikes */ 63 64 # if defined(__clang__) 65 /* clang-specific section */ 66 # endif 67 68 # define OSVR_FUNC_NONNULL(X) __attribute__((__nonnull__ X)) 69 # define OSVR_RETURN_WARN_UNUSED __attribute__((warn_unused_result)) 70 71 /* end of gcc section and compiler detection */ 72 # endif 73 74 /* end of ndef disable analysis */ 75 #endif 76 77 /* Fallback declarations */ 78 /** 79 @defgroup annotation_macros Static analysis annotation macros 80 @brief Wrappers for Microsoft's SAL annotations and others 81 @ingroup Util 82 83 Use of these is optional, but recommended particularly for C APIs, 84 as well as any methods handling a buffer with a length. 85 @{ 86 */ 87 /** @name Parameter annotations 88 89 These indicate the role and valid values for parameters to functions. 90 91 At most one of these should be placed before a parameter's type name in the 92 function parameter list, in both the declaration and definition. (They must 93 match!) 94 @{ 95 */ 96 /** @def OSVR_IN 97 @brief Indicates a required function parameter that serves only as input. 98 */ 99 #ifndef OSVR_IN 100 # define OSVR_IN 101 #endif 102 103 /** @def OSVR_IN_PTR 104 @brief Indicates a required pointer (non-null) function parameter that 105 serves only as input. 106 */ 107 #ifndef OSVR_IN_PTR 108 # define OSVR_IN_PTR 109 #endif 110 111 /** @def OSVR_IN_OPT 112 @brief Indicates a function parameter (pointer) that serves only as input, 113 but is optional and might be NULL. 114 */ 115 #ifndef OSVR_IN_OPT 116 # define OSVR_IN_OPT 117 #endif 118 119 /** @def OSVR_IN_STRZ 120 @brief Indicates a null-terminated string function parameter that serves 121 only as input. 122 */ 123 #ifndef OSVR_IN_STRZ 124 # define OSVR_IN_STRZ 125 #endif 126 127 /** @def OSVR_IN_READS(NUM_ELEMENTS) 128 @brief Indicates a buffer containing input with the specified number of 129 elements. 130 131 The specified number of elements is typically the name of another parameter. 132 */ 133 #ifndef OSVR_IN_READS 134 # define OSVR_IN_READS(NUM_ELEMENTS) 135 #endif 136 137 /** @def OSVR_OUT 138 @brief Indicates a required function parameter that serves only as output. 139 In C code, since this usually means "pointer", you probably want 140 OSVR_OUT_PTR instead. 141 */ 142 #ifndef OSVR_OUT 143 # define OSVR_OUT 144 #endif 145 146 /** @def OSVR_OUT_PTR 147 @brief Indicates a required pointer (non-null) function parameter that 148 serves only as output. 149 */ 150 #ifndef OSVR_OUT_PTR 151 # define OSVR_OUT_PTR 152 #endif 153 154 /** @def OSVR_OUT_OPT 155 @brief Indicates a function parameter (pointer) that serves only as output, 156 but is optional and might be NULL 157 */ 158 #ifndef OSVR_OUT_OPT 159 # define OSVR_OUT_OPT 160 #endif 161 162 /** @def OSVR_INOUT 163 @brief Indicates a required function parameter that is both read and written 164 to. 165 166 In C code, since this usually means "pointer", you probably want 167 OSVR_INOUT_PTR instead. 168 */ 169 #ifndef OSVR_INOUT 170 # define OSVR_INOUT 171 #endif 172 173 /** @def OSVR_INOUT_PTR 174 @brief Indicates a required pointer (non-null) function parameter that is 175 both read and written to. 176 */ 177 #ifndef OSVR_INOUT_PTR 178 # define OSVR_INOUT_PTR 179 #endif 180 181 /* End of parameter annotations. */ 182 /** @} */ 183 184 /** @name Function annotations 185 186 These indicate particular relevant aspects about a function. Some 187 duplicate the effective meaning of parameter annotations: applying both 188 allows the fullest extent of static analysis tools to analyze the code, 189 and in some compilers, generate warnings. 190 191 @{ 192 */ 193 /** @def OSVR_FUNC_NONNULL(X) 194 @brief Indicates the parameter(s) that must be non-null. 195 196 @param X A parenthesized list of parameters by number (1-based index) 197 198 Should be placed after a function declaration (but before the 199 semicolon). Repeating in the definition is not needed. 200 */ 201 #ifndef OSVR_FUNC_NONNULL 202 # define OSVR_FUNC_NONNULL(X) 203 #endif 204 205 /** @def OSVR_RETURN_WARN_UNUSED 206 @brief Indicates the function has a return value that must be used (either a 207 security problem or an obvious bug if not). 208 209 Should be placed before the return value (and virtual keyword, if 210 applicable) in both declaration and definition. 211 */ 212 #ifndef OSVR_RETURN_WARN_UNUSED 213 # define OSVR_RETURN_WARN_UNUSED 214 #endif 215 /* End of function annotations. */ 216 /** @} */ 217 218 /** @def OSVR_RETURN_SUCCESS_CONDITION 219 @brief Applied to a typedef, indicates the condition for `return` under 220 which a function returning it should be considered to have succeeded (thus 221 holding certain specifications). 222 223 Should be placed before the typename in a typedef, with the parameter 224 including the keyword `return` to substitute for the return value. 225 */ 226 #ifndef OSVR_RETURN_SUCCESS_CONDITION 227 # define OSVR_RETURN_SUCCESS_CONDITION(X) 228 #endif 229 230 /* End of annotation group. */ 231 /** @} */ 232 #endif