Quelle  AnnotationMacrosC.h   Sprache: C

/** @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.
    <http://sensics.com/osvr>
*/

/*
// 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 <sal.h>

#    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