/** @file @brief Header containing macros for source-level annotation. In theory, supporting MSVC SAL, as well as compatible GCC and Clang attributes. In practice, expanded as time allows and requires. Must be c-safe! @date 2014 @author Sensics, Inc. */ /* // Copyright 2014 Sensics, Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. */ #ifndef INCLUDED_AnnotationMacrosC_h_GUID_48538D9B_35E3_4E9A_D2B0_D83D51DD5900 #define INCLUDED_AnnotationMacrosC_h_GUID_48538D9B_35E3_4E9A_D2B0_D83D51DD5900 #ifndef OSVR_DISABLE_ANALYSIS # if defined(_MSC_VER) && (_MSC_VER >= 1700) /* Visual C++ (2012 and newer) */ /* Using SAL attribute format: * http://msdn.microsoft.com/en-us/library/ms182032(v=vs.120).aspx */ # include # define OSVR_IN _In_ # define OSVR_IN_PTR _In_ # define OSVR_IN_OPT _In_opt_ # define OSVR_IN_STRZ _In_z_ # define OSVR_IN_READS(NUM_ELEMENTS) _In_reads_(NUM_ELEMENTS) # define OSVR_OUT _Out_ # define OSVR_OUT_PTR _Outptr_ # define OSVR_OUT_OPT _Out_opt_ # define OSVR_INOUT _Inout_ # define OSVR_INOUT_PTR _Inout_ # define OSVR_RETURN_WARN_UNUSED _Must_inspect_result_ # define OSVR_RETURN_SUCCESS_CONDITION(X) _Return_type_success_(X) /* end of msvc section */ # elif defined(__GNUC__) && (__GNUC__ >= 4) /* section for GCC and GCC-alikes */ # if defined(__clang__) /* clang-specific section */ # endif # define OSVR_FUNC_NONNULL(X) __attribute__((__nonnull__ X)) # define OSVR_RETURN_WARN_UNUSED __attribute__((warn_unused_result)) /* end of gcc section and compiler detection */ # endif /* end of ndef disable analysis */ #endif /* Fallback declarations */ /** @defgroup annotation_macros Static analysis annotation macros @brief Wrappers for Microsoft's SAL annotations and others @ingroup Util Use of these is optional, but recommended particularly for C APIs, as well as any methods handling a buffer with a length. @{ */ /** @name Parameter annotations These indicate the role and valid values for parameters to functions. At most one of these should be placed before a parameter's type name in the function parameter list, in both the declaration and definition. (They must match!) @{ */ /** @def OSVR_IN @brief Indicates a required function parameter that serves only as input. */ #ifndef OSVR_IN # define OSVR_IN #endif /** @def OSVR_IN_PTR @brief Indicates a required pointer (non-null) function parameter that serves only as input. */ #ifndef OSVR_IN_PTR # define OSVR_IN_PTR #endif /** @def OSVR_IN_OPT @brief Indicates a function parameter (pointer) that serves only as input, but is optional and might be NULL. */ #ifndef OSVR_IN_OPT # define OSVR_IN_OPT #endif /** @def OSVR_IN_STRZ @brief Indicates a null-terminated string function parameter that serves only as input. */ #ifndef OSVR_IN_STRZ # define OSVR_IN_STRZ #endif /** @def OSVR_IN_READS(NUM_ELEMENTS) @brief Indicates a buffer containing input with the specified number of elements. The specified number of elements is typically the name of another parameter. */ #ifndef OSVR_IN_READS # define OSVR_IN_READS(NUM_ELEMENTS) #endif /** @def OSVR_OUT @brief Indicates a required function parameter that serves only as output. In C code, since this usually means "pointer", you probably want OSVR_OUT_PTR instead. */ #ifndef OSVR_OUT # define OSVR_OUT #endif /** @def OSVR_OUT_PTR @brief Indicates a required pointer (non-null) function parameter that serves only as output. */ #ifndef OSVR_OUT_PTR # define OSVR_OUT_PTR #endif /** @def OSVR_OUT_OPT @brief Indicates a function parameter (pointer) that serves only as output, but is optional and might be NULL */ #ifndef OSVR_OUT_OPT # define OSVR_OUT_OPT #endif /** @def OSVR_INOUT @brief Indicates a required function parameter that is both read and written to. In C code, since this usually means "pointer", you probably want OSVR_INOUT_PTR instead. */ #ifndef OSVR_INOUT # define OSVR_INOUT #endif /** @def OSVR_INOUT_PTR @brief Indicates a required pointer (non-null) function parameter that is both read and written to. */ #ifndef OSVR_INOUT_PTR # define OSVR_INOUT_PTR #endif /* End of parameter annotations. */ /** @} */ /** @name Function annotations These indicate particular relevant aspects about a function. Some duplicate the effective meaning of parameter annotations: applying both allows the fullest extent of static analysis tools to analyze the code, and in some compilers, generate warnings. @{ */ /** @def OSVR_FUNC_NONNULL(X) @brief Indicates the parameter(s) that must be non-null. @param X A parenthesized list of parameters by number (1-based index) Should be placed after a function declaration (but before the semicolon). Repeating in the definition is not needed. */ #ifndef OSVR_FUNC_NONNULL # define OSVR_FUNC_NONNULL(X) #endif /** @def OSVR_RETURN_WARN_UNUSED @brief Indicates the function has a return value that must be used (either a security problem or an obvious bug if not). Should be placed before the return value (and virtual keyword, if applicable) in both declaration and definition. */ #ifndef OSVR_RETURN_WARN_UNUSED # define OSVR_RETURN_WARN_UNUSED #endif /* End of function annotations. */ /** @} */ /** @def OSVR_RETURN_SUCCESS_CONDITION @brief Applied to a typedef, indicates the condition for `return` under which a function returning it should be considered to have succeeded (thus holding certain specifications). Should be placed before the typename in a typedef, with the parameter including the keyword `return` to substitute for the return value. */ #ifndef OSVR_RETURN_SUCCESS_CONDITION # define OSVR_RETURN_SUCCESS_CONDITION(X) #endif /* End of annotation group. */ /** @} */ #endif