1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
/** @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
|
