third_party: Update cmocka to version 1.1.3
[samba.git] / third_party / cmocka / cmocka.h
1 /*
2  * Copyright 2008 Google Inc.
3  * Copyright 2014-2018 Andreas Schneider <asn@cryptomilk.org>
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef CMOCKA_H_
18 #define CMOCKA_H_
19
20 #ifdef _WIN32
21 # ifdef _MSC_VER
22
23 #define __func__ __FUNCTION__
24
25 # ifndef inline
26 #define inline __inline
27 # endif /* inline */
28
29 #  if _MSC_VER < 1500
30 #   ifdef __cplusplus
31 extern "C" {
32 #   endif   /* __cplusplus */
33 int __stdcall IsDebuggerPresent();
34 #   ifdef __cplusplus
35 } /* extern "C" */
36 #   endif   /* __cplusplus */
37 #  endif  /* _MSC_VER < 1500 */
38 # endif /* _MSC_VER */
39 #endif  /* _WIN32 */
40
41 /**
42  * @defgroup cmocka The CMocka API
43  *
44  * These headers or their equivalents should be included prior to including
45  * this header file.
46  * @code
47  * #include <stdarg.h>
48  * #include <stddef.h>
49  * #include <setjmp.h>
50  * @endcode
51  *
52  * This allows test applications to use custom definitions of C standard
53  * library functions and types.
54  *
55  * @{
56  */
57
58 /* If __WORDSIZE is not set, try to figure it out and default to 32 bit. */
59 #ifndef __WORDSIZE
60 # if (defined(__x86_64__) && !defined(__ILP32__)) || defined(__sparc_v9__) || defined(__sparcv9)
61 #  define __WORDSIZE 64
62 # else
63 #  define __WORDSIZE 32
64 # endif
65 #endif
66
67 #ifdef DOXYGEN
68 /**
69  * Largest integral type.  This type should be large enough to hold any
70  * pointer or integer supported by the compiler.
71  */
72 typedef uintmax_t LargestIntegralType;
73 #else /* DOXGEN */
74 #ifndef LargestIntegralType
75 # if __WORDSIZE == 64 && !defined(_WIN64)
76 #  define LargestIntegralType unsigned long int
77 # else
78 #  define LargestIntegralType unsigned long long int
79 # endif
80 #endif /* LargestIntegralType */
81 #endif /* DOXYGEN */
82
83 /* Printf format used to display LargestIntegralType as a hexidecimal. */
84 #ifndef LargestIntegralTypePrintfFormat
85 # ifdef _WIN32
86 #  define LargestIntegralTypePrintfFormat "0x%I64x"
87 # else
88 #  if __WORDSIZE == 64
89 #   define LargestIntegralTypePrintfFormat "%#lx"
90 #  else
91 #   define LargestIntegralTypePrintfFormat "%#llx"
92 #  endif
93 # endif /* _WIN32 */
94 #endif /* LargestIntegralTypePrintfFormat */
95
96 /* Printf format used to display LargestIntegralType as a decimal. */
97 #ifndef LargestIntegralTypePrintfFormatDecimal
98 # ifdef _WIN32
99 #  define LargestIntegralTypePrintfFormatDecimal "%I64u"
100 # else
101 #  if __WORDSIZE == 64
102 #   define LargestIntegralTypePrintfFormatDecimal "%lu"
103 #  else
104 #   define LargestIntegralTypePrintfFormatDecimal "%llu"
105 #  endif
106 # endif /* _WIN32 */
107 #endif /* LargestIntegralTypePrintfFormat */
108
109 /* Perform an unsigned cast to LargestIntegralType. */
110 #define cast_to_largest_integral_type(value) \
111     ((LargestIntegralType)(value))
112
113 /* Smallest integral type capable of holding a pointer. */
114 #if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED)
115 # if defined(_WIN32)
116     /* WIN32 is an ILP32 platform */
117     typedef unsigned int uintptr_t;
118 # elif defined(_WIN64)
119     typedef unsigned long int uintptr_t
120 # else /* _WIN32 */
121
122 /* ILP32 and LP64 platforms */
123 #  ifdef __WORDSIZE /* glibc */
124 #   if __WORDSIZE == 64
125       typedef unsigned long int uintptr_t;
126 #   else
127       typedef unsigned int uintptr_t;
128 #   endif /* __WORDSIZE == 64 */
129 #  else /* __WORDSIZE */
130 #   if defined(_LP64) || defined(_I32LPx)
131       typedef unsigned long int uintptr_t;
132 #   else
133       typedef unsigned int uintptr_t;
134 #   endif
135 #  endif /* __WORDSIZE */
136 # endif /* _WIN32 */
137
138 # define _UINTPTR_T
139 # define _UINTPTR_T_DEFINED
140 #endif /* !defined(_UINTPTR_T) || !defined(_UINTPTR_T_DEFINED) */
141
142 /* Perform an unsigned cast to uintptr_t. */
143 #define cast_to_pointer_integral_type(value) \
144     ((uintptr_t)((size_t)(value)))
145
146 /* Perform a cast of a pointer to LargestIntegralType */
147 #define cast_ptr_to_largest_integral_type(value) \
148 cast_to_largest_integral_type(cast_to_pointer_integral_type(value))
149
150 /* GCC have printf type attribute check.  */
151 #ifdef __GNUC__
152 #define CMOCKA_PRINTF_ATTRIBUTE(a,b) \
153     __attribute__ ((__format__ (__printf__, a, b)))
154 #else
155 #define CMOCKA_PRINTF_ATTRIBUTE(a,b)
156 #endif /* __GNUC__ */
157
158 #if defined(__GNUC__)
159 #define CMOCKA_DEPRECATED __attribute__ ((deprecated))
160 #elif defined(_MSC_VER)
161 #define CMOCKA_DEPRECATED __declspec(deprecated)
162 #else
163 #define CMOCKA_DEPRECATED
164 #endif
165
166 #define WILL_RETURN_ALWAYS -1
167 #define WILL_RETURN_ONCE -2
168
169 /**
170  * @defgroup cmocka_mock Mock Objects
171  * @ingroup cmocka
172  *
173  * Mock objects mock objects are simulated objects that mimic the behavior of
174  * real objects. Instead of calling the real objects, the tested object calls a
175  * mock object that merely asserts that the correct methods were called, with
176  * the expected parameters, in the correct order.
177  *
178  * <ul>
179  * <li><strong>will_return(function, value)</strong> - The will_return() macro
180  * pushes a value onto a stack of mock values. This macro is intended to be
181  * used by the unit test itself, while programming the behaviour of the mocked
182  * object.</li>
183  *
184  * <li><strong>mock()</strong> - the mock macro pops a value from a stack of
185  * test values. The user of the mock() macro is the mocked object that uses it
186  * to learn how it should behave.</li>
187  * </ul>
188  *
189  * Because the will_return() and mock() are intended to be used in pairs, the
190  * cmocka library would fail the test if there are more values pushed onto the
191  * stack using will_return() than consumed with mock() and vice-versa.
192  *
193  * The following unit test stub illustrates how would a unit test instruct the
194  * mock object to return a particular value:
195  *
196  * @code
197  * will_return(chef_cook, "hotdog");
198  * will_return(chef_cook, 0);
199  * @endcode
200  *
201  * Now the mock object can check if the parameter it received is the parameter
202  * which is expected by the test driver. This can be done the following way:
203  *
204  * @code
205  * int chef_cook(const char *order, char **dish_out)
206  * {
207  *     check_expected(order);
208  * }
209  * @endcode
210  *
211  * For a complete example please at a look
212  * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>.
213  *
214  * @{
215  */
216
217 #ifdef DOXYGEN
218 /**
219  * @brief Retrieve a return value of the current function.
220  *
221  * @return The value which was stored to return by this function.
222  *
223  * @see will_return()
224  */
225 LargestIntegralType mock(void);
226 #else
227 #define mock() _mock(__func__, __FILE__, __LINE__)
228 #endif
229
230 #ifdef DOXYGEN
231 /**
232  * @brief Retrieve a typed return value of the current function.
233  *
234  * The value would be casted to type internally to avoid having the
235  * caller to do the cast manually.
236  *
237  * @param[in]  #type  The expected type of the return value
238  *
239  * @return The value which was stored to return by this function.
240  *
241  * @code
242  * int param;
243  *
244  * param = mock_type(int);
245  * @endcode
246  *
247  * @see will_return()
248  * @see mock()
249  * @see mock_ptr_type()
250  */
251 #type mock_type(#type);
252 #else
253 #define mock_type(type) ((type) mock())
254 #endif
255
256 #ifdef DOXYGEN
257 /**
258  * @brief Retrieve a typed return value of the current function.
259  *
260  * The value would be casted to type internally to avoid having the
261  * caller to do the cast manually but also casted to uintptr_t to make
262  * sure the result has a valid size to be used as a pointer.
263  *
264  * @param[in]  #type  The expected type of the return value
265  *
266  * @return The value which was stored to return by this function.
267  *
268  * @code
269  * char *param;
270  *
271  * param = mock_ptr_type(char *);
272  * @endcode
273  *
274  * @see will_return()
275  * @see mock()
276  * @see mock_type()
277  */
278 type mock_ptr_type(#type);
279 #else
280 #define mock_ptr_type(type) ((type) (uintptr_t) mock())
281 #endif
282
283
284 #ifdef DOXYGEN
285 /**
286  * @brief Store a value to be returned by mock() later.
287  *
288  * @param[in]  #function  The function which should return the given value.
289  *
290  * @param[in]  value The value to be returned by mock().
291  *
292  * @code
293  * int return_integer(void)
294  * {
295  *      return (int)mock();
296  * }
297  *
298  * static void test_integer_return(void **state)
299  * {
300  *      will_return(return_integer, 42);
301  *
302  *      assert_int_equal(my_function_calling_return_integer(), 42);
303  * }
304  * @endcode
305  *
306  * @see mock()
307  * @see will_return_count()
308  */
309 void will_return(#function, LargestIntegralType value);
310 #else
311 #define will_return(function, value) \
312     _will_return(#function, __FILE__, __LINE__, \
313                  cast_to_largest_integral_type(value), 1)
314 #endif
315
316 #ifdef DOXYGEN
317 /**
318  * @brief Store a value to be returned by mock() later.
319  *
320  * @param[in]  #function  The function which should return the given value.
321  *
322  * @param[in]  value The value to be returned by mock().
323  *
324  * @param[in]  count The parameter indicates the number of times the value should
325  *                   be returned by mock(). If count is set to -1, the value
326  *                   will always be returned but must be returned at least once.
327  *                   If count is set to -2, the value will always be returned
328  *                   by mock(), but is not required to be returned.
329  *
330  * @see mock()
331  */
332 void will_return_count(#function, LargestIntegralType value, int count);
333 #else
334 #define will_return_count(function, value, count) \
335     _will_return(#function, __FILE__, __LINE__, \
336                  cast_to_largest_integral_type(value), count)
337 #endif
338
339 #ifdef DOXYGEN
340 /**
341  * @brief Store a value that will be always returned by mock().
342  *
343  * @param[in]  #function  The function which should return the given value.
344  *
345  * @param[in]  #value The value to be returned by mock().
346  *
347  * This is equivalent to:
348  * @code
349  * will_return_count(function, value, -1);
350  * @endcode
351  *
352  * @see will_return_count()
353  * @see mock()
354  */
355 void will_return_always(#function, LargestIntegralType value);
356 #else
357 #define will_return_always(function, value) \
358     will_return_count(function, (value), WILL_RETURN_ALWAYS)
359 #endif
360
361 #ifdef DOXYGEN
362 /**
363  * @brief Store a value that may be always returned by mock().
364  *
365  * This stores a value which will always be returned by mock() but is not
366  * required to be returned by at least one call to mock(). Therefore,
367  * in contrast to will_return_always() which causes a test failure if it
368  * is not returned at least once, will_return_maybe() will never cause a test
369  * to fail if its value is not returned.
370  *
371  * @param[in]  #function  The function which should return the given value.
372  *
373  * @param[in]  #value The value to be returned by mock().
374  *
375  * This is equivalent to:
376  * @code
377  * will_return_count(function, value, -2);
378  * @endcode
379  *
380  * @see will_return_count()
381  * @see mock()
382  */
383 void will_return_maybe(#function, LargestIntegralType value);
384 #else
385 #define will_return_maybe(function, value) \
386     will_return_count(function, (value), WILL_RETURN_ONCE)
387 #endif
388 /** @} */
389
390 /**
391  * @defgroup cmocka_param Checking Parameters
392  * @ingroup cmocka
393  *
394  * Functionality to store expected values for mock function parameters.
395  *
396  * In addition to storing the return values of mock functions, cmocka provides
397  * functionality to store expected values for mock function parameters using
398  * the expect_*() functions provided. A mock function parameter can then be
399  * validated using the check_expected() macro.
400  *
401  * Successive calls to expect_*() macros for a parameter queues values to check
402  * the specified parameter. check_expected() checks a function parameter
403  * against the next value queued using expect_*(), if the parameter check fails
404  * a test failure is signalled. In addition if check_expected() is called and
405  * no more parameter values are queued a test failure occurs.
406  *
407  * The following test stub illustrates how to do this. First is the the function
408  * we call in the test driver:
409  *
410  * @code
411  * static void test_driver(void **state)
412  * {
413  *     expect_string(chef_cook, order, "hotdog");
414  * }
415  * @endcode
416  *
417  * Now the chef_cook function can check if the parameter we got passed is the
418  * parameter which is expected by the test driver. This can be done the
419  * following way:
420  *
421  * @code
422  * int chef_cook(const char *order, char **dish_out)
423  * {
424  *     check_expected(order);
425  * }
426  * @endcode
427  *
428  * For a complete example please at a look at
429  * <a href="http://git.cryptomilk.org/projects/cmocka.git/tree/example/chef_wrap/waiter_test_wrap.c">here</a>
430  *
431  * @{
432  */
433
434 /*
435  * Add a custom parameter checking function.  If the event parameter is NULL
436  * the event structure is allocated internally by this function.  If event
437  * parameter is provided it must be allocated on the heap and doesn't need to
438  * be deallocated by the caller.
439  */
440 #ifdef DOXYGEN
441 /**
442  * @brief Add a custom parameter checking function.
443  *
444  * If the event parameter is NULL the event structure is allocated internally
445  * by this function. If the parameter is provided it must be allocated on the
446  * heap and doesn't need to be deallocated by the caller.
447  *
448  * @param[in]  #function  The function to add a custom parameter checking
449  *                        function for.
450  *
451  * @param[in]  #parameter The parameters passed to the function.
452  *
453  * @param[in]  #check_function  The check function to call.
454  *
455  * @param[in]  check_data       The data to pass to the check function.
456  */
457 void expect_check(#function, #parameter, #check_function, const void *check_data);
458 #else
459 #define expect_check(function, parameter, check_function, check_data) \
460     _expect_check(#function, #parameter, __FILE__, __LINE__, check_function, \
461                   cast_to_largest_integral_type(check_data), NULL, 1)
462 #endif
463
464 #ifdef DOXYGEN
465 /**
466  * @brief Add an event to check if the parameter value is part of the provided
467  *        array.
468  *
469  * The event is triggered by calling check_expected() in the mocked function.
470  *
471  * @param[in]  #function  The function to add the check for.
472  *
473  * @param[in]  #parameter The name of the parameter passed to the function.
474  *
475  * @param[in]  value_array[] The array to check for the value.
476  *
477  * @see check_expected().
478  */
479 void expect_in_set(#function, #parameter, LargestIntegralType value_array[]);
480 #else
481 #define expect_in_set(function, parameter, value_array) \
482     expect_in_set_count(function, parameter, value_array, 1)
483 #endif
484
485 #ifdef DOXYGEN
486 /**
487  * @brief Add an event to check if the parameter value is part of the provided
488  *        array.
489  *
490  * The event is triggered by calling check_expected() in the mocked function.
491  *
492  * @param[in]  #function  The function to add the check for.
493  *
494  * @param[in]  #parameter The name of the parameter passed to the function.
495  *
496  * @param[in]  value_array[] The array to check for the value.
497  *
498  * @param[in]  count  The count parameter returns the number of times the value
499  *                    should be returned by check_expected(). If count is set
500  *                    to -1 the value will always be returned.
501  *
502  * @see check_expected().
503  */
504 void expect_in_set_count(#function, #parameter, LargestIntegralType value_array[], size_t count);
505 #else
506 #define expect_in_set_count(function, parameter, value_array, count) \
507     _expect_in_set(#function, #parameter, __FILE__, __LINE__, value_array, \
508                    sizeof(value_array) / sizeof((value_array)[0]), count)
509 #endif
510
511 #ifdef DOXYGEN
512 /**
513  * @brief Add an event to check if the parameter value is not part of the
514  *        provided array.
515  *
516  * The event is triggered by calling check_expected() in the mocked function.
517  *
518  * @param[in]  #function  The function to add the check for.
519  *
520  * @param[in]  #parameter The name of the parameter passed to the function.
521  *
522  * @param[in]  value_array[] The array to check for the value.
523  *
524  * @see check_expected().
525  */
526 void expect_not_in_set(#function, #parameter, LargestIntegralType value_array[]);
527 #else
528 #define expect_not_in_set(function, parameter, value_array) \
529     expect_not_in_set_count(function, parameter, value_array, 1)
530 #endif
531
532 #ifdef DOXYGEN
533 /**
534  * @brief Add an event to check if the parameter value is not part of the
535  *        provided array.
536  *
537  * The event is triggered by calling check_expected() in the mocked function.
538  *
539  * @param[in]  #function  The function to add the check for.
540  *
541  * @param[in]  #parameter The name of the parameter passed to the function.
542  *
543  * @param[in]  value_array[] The array to check for the value.
544  *
545  * @param[in]  count  The count parameter returns the number of times the value
546  *                    should be returned by check_expected(). If count is set
547  *                    to -1 the value will always be returned.
548  *
549  * @see check_expected().
550  */
551 void expect_not_in_set_count(#function, #parameter, LargestIntegralType value_array[], size_t count);
552 #else
553 #define expect_not_in_set_count(function, parameter, value_array, count) \
554     _expect_not_in_set( \
555         #function, #parameter, __FILE__, __LINE__, value_array, \
556         sizeof(value_array) / sizeof((value_array)[0]), count)
557 #endif
558
559
560 #ifdef DOXYGEN
561 /**
562  * @brief Add an event to check a parameter is inside a numerical range.
563  * The check would succeed if minimum <= value <= maximum.
564  *
565  * The event is triggered by calling check_expected() in the mocked function.
566  *
567  * @param[in]  #function  The function to add the check for.
568  *
569  * @param[in]  #parameter The name of the parameter passed to the function.
570  *
571  * @param[in]  minimum  The lower boundary of the interval to check against.
572  *
573  * @param[in]  maximum  The upper boundary of the interval to check against.
574  *
575  * @see check_expected().
576  */
577 void expect_in_range(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum);
578 #else
579 #define expect_in_range(function, parameter, minimum, maximum) \
580     expect_in_range_count(function, parameter, minimum, maximum, 1)
581 #endif
582
583 #ifdef DOXYGEN
584 /**
585  * @brief Add an event to repeatedly check a parameter is inside a
586  * numerical range. The check would succeed if minimum <= value <= maximum.
587  *
588  * The event is triggered by calling check_expected() in the mocked function.
589  *
590  * @param[in]  #function  The function to add the check for.
591  *
592  * @param[in]  #parameter The name of the parameter passed to the function.
593  *
594  * @param[in]  minimum  The lower boundary of the interval to check against.
595  *
596  * @param[in]  maximum  The upper boundary of the interval to check against.
597  *
598  * @param[in]  count  The count parameter returns the number of times the value
599  *                    should be returned by check_expected(). If count is set
600  *                    to -1 the value will always be returned.
601  *
602  * @see check_expected().
603  */
604 void expect_in_range_count(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum, size_t count);
605 #else
606 #define expect_in_range_count(function, parameter, minimum, maximum, count) \
607     _expect_in_range(#function, #parameter, __FILE__, __LINE__, minimum, \
608                      maximum, count)
609 #endif
610
611 #ifdef DOXYGEN
612 /**
613  * @brief Add an event to check a parameter is outside a numerical range.
614  * The check would succeed if minimum > value > maximum.
615  *
616  * The event is triggered by calling check_expected() in the mocked function.
617  *
618  * @param[in]  #function  The function to add the check for.
619  *
620  * @param[in]  #parameter The name of the parameter passed to the function.
621  *
622  * @param[in]  minimum  The lower boundary of the interval to check against.
623  *
624  * @param[in]  maximum  The upper boundary of the interval to check against.
625  *
626  * @see check_expected().
627  */
628 void expect_not_in_range(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum);
629 #else
630 #define expect_not_in_range(function, parameter, minimum, maximum) \
631     expect_not_in_range_count(function, parameter, minimum, maximum, 1)
632 #endif
633
634 #ifdef DOXYGEN
635 /**
636  * @brief Add an event to repeatedly check a parameter is outside a
637  * numerical range. The check would succeed if minimum > value > maximum.
638  *
639  * The event is triggered by calling check_expected() in the mocked function.
640  *
641  * @param[in]  #function  The function to add the check for.
642  *
643  * @param[in]  #parameter The name of the parameter passed to the function.
644  *
645  * @param[in]  minimum  The lower boundary of the interval to check against.
646  *
647  * @param[in]  maximum  The upper boundary of the interval to check against.
648  *
649  * @param[in]  count  The count parameter returns the number of times the value
650  *                    should be returned by check_expected(). If count is set
651  *                    to -1 the value will always be returned.
652  *
653  * @see check_expected().
654  */
655 void expect_not_in_range_count(#function, #parameter, LargestIntegralType minimum, LargestIntegralType maximum, size_t count);
656 #else
657 #define expect_not_in_range_count(function, parameter, minimum, maximum, \
658                                   count) \
659     _expect_not_in_range(#function, #parameter, __FILE__, __LINE__, \
660                          minimum, maximum, count)
661 #endif
662
663 #ifdef DOXYGEN
664 /**
665  * @brief Add an event to check if a parameter is the given value.
666  *
667  * The event is triggered by calling check_expected() in the mocked function.
668  *
669  * @param[in]  #function  The function to add the check for.
670  *
671  * @param[in]  #parameter The name of the parameter passed to the function.
672  *
673  * @param[in]  value  The value to check.
674  *
675  * @see check_expected().
676  */
677 void expect_value(#function, #parameter, LargestIntegralType value);
678 #else
679 #define expect_value(function, parameter, value) \
680     expect_value_count(function, parameter, value, 1)
681 #endif
682
683 #ifdef DOXYGEN
684 /**
685  * @brief Add an event to repeatedly check if a parameter is the given value.
686  *
687  * The event is triggered by calling check_expected() in the mocked function.
688  *
689  * @param[in]  #function  The function to add the check for.
690  *
691  * @param[in]  #parameter The name of the parameter passed to the function.
692  *
693  * @param[in]  value  The value to check.
694  *
695  * @param[in]  count  The count parameter returns the number of times the value
696  *                    should be returned by check_expected(). If count is set
697  *                    to -1 the value will always be returned.
698  *
699  * @see check_expected().
700  */
701 void expect_value_count(#function, #parameter, LargestIntegralType value, size_t count);
702 #else
703 #define expect_value_count(function, parameter, value, count) \
704     _expect_value(#function, #parameter, __FILE__, __LINE__, \
705                   cast_to_largest_integral_type(value), count)
706 #endif
707
708 #ifdef DOXYGEN
709 /**
710  * @brief Add an event to check if a parameter isn't the given value.
711  *
712  * The event is triggered by calling check_expected() in the mocked function.
713  *
714  * @param[in]  #function  The function to add the check for.
715  *
716  * @param[in]  #parameter The name of the parameter passed to the function.
717  *
718  * @param[in]  value  The value to check.
719  *
720  * @see check_expected().
721  */
722 void expect_not_value(#function, #parameter, LargestIntegralType value);
723 #else
724 #define expect_not_value(function, parameter, value) \
725     expect_not_value_count(function, parameter, value, 1)
726 #endif
727
728 #ifdef DOXYGEN
729 /**
730  * @brief Add an event to repeatedly check if a parameter isn't the given value.
731  *
732  * The event is triggered by calling check_expected() in the mocked function.
733  *
734  * @param[in]  #function  The function to add the check for.
735  *
736  * @param[in]  #parameter The name of the parameter passed to the function.
737  *
738  * @param[in]  value  The value to check.
739  *
740  * @param[in]  count  The count parameter returns the number of times the value
741  *                    should be returned by check_expected(). If count is set
742  *                    to -1 the value will always be returned.
743  *
744  * @see check_expected().
745  */
746 void expect_not_value_count(#function, #parameter, LargestIntegralType value, size_t count);
747 #else
748 #define expect_not_value_count(function, parameter, value, count) \
749     _expect_not_value(#function, #parameter, __FILE__, __LINE__, \
750                       cast_to_largest_integral_type(value), count)
751 #endif
752
753 #ifdef DOXYGEN
754 /**
755  * @brief Add an event to check if the parameter value is equal to the
756  *        provided string.
757  *
758  * The event is triggered by calling check_expected() in the mocked function.
759  *
760  * @param[in]  #function  The function to add the check for.
761  *
762  * @param[in]  #parameter The name of the parameter passed to the function.
763  *
764  * @param[in]  string   The string value to compare.
765  *
766  * @see check_expected().
767  */
768 void expect_string(#function, #parameter, const char *string);
769 #else
770 #define expect_string(function, parameter, string) \
771     expect_string_count(function, parameter, string, 1)
772 #endif
773
774 #ifdef DOXYGEN
775 /**
776  * @brief Add an event to check if the parameter value is equal to the
777  *        provided string.
778  *
779  * The event is triggered by calling check_expected() in the mocked function.
780  *
781  * @param[in]  #function  The function to add the check for.
782  *
783  * @param[in]  #parameter The name of the parameter passed to the function.
784  *
785  * @param[in]  string   The string value to compare.
786  *
787  * @param[in]  count  The count parameter returns the number of times the value
788  *                    should be returned by check_expected(). If count is set
789  *                    to -1 the value will always be returned.
790  *
791  * @see check_expected().
792  */
793 void expect_string_count(#function, #parameter, const char *string, size_t count);
794 #else
795 #define expect_string_count(function, parameter, string, count) \
796     _expect_string(#function, #parameter, __FILE__, __LINE__, \
797                    (const char*)(string), count)
798 #endif
799
800 #ifdef DOXYGEN
801 /**
802  * @brief Add an event to check if the parameter value isn't equal to the
803  *        provided string.
804  *
805  * The event is triggered by calling check_expected() in the mocked function.
806  *
807  * @param[in]  #function  The function to add the check for.
808  *
809  * @param[in]  #parameter The name of the parameter passed to the function.
810  *
811  * @param[in]  string   The string value to compare.
812  *
813  * @see check_expected().
814  */
815 void expect_not_string(#function, #parameter, const char *string);
816 #else
817 #define expect_not_string(function, parameter, string) \
818     expect_not_string_count(function, parameter, string, 1)
819 #endif
820
821 #ifdef DOXYGEN
822 /**
823  * @brief Add an event to check if the parameter value isn't equal to the
824  *        provided string.
825  *
826  * The event is triggered by calling check_expected() in the mocked function.
827  *
828  * @param[in]  #function  The function to add the check for.
829  *
830  * @param[in]  #parameter The name of the parameter passed to the function.
831  *
832  * @param[in]  string   The string value to compare.
833  *
834  * @param[in]  count  The count parameter returns the number of times the value
835  *                    should be returned by check_expected(). If count is set
836  *                    to -1 the value will always be returned.
837  *
838  * @see check_expected().
839  */
840 void expect_not_string_count(#function, #parameter, const char *string, size_t count);
841 #else
842 #define expect_not_string_count(function, parameter, string, count) \
843     _expect_not_string(#function, #parameter, __FILE__, __LINE__, \
844                        (const char*)(string), count)
845 #endif
846
847 #ifdef DOXYGEN
848 /**
849  * @brief Add an event to check if the parameter does match an area of memory.
850  *
851  * The event is triggered by calling check_expected() in the mocked function.
852  *
853  * @param[in]  #function  The function to add the check for.
854  *
855  * @param[in]  #parameter The name of the parameter passed to the function.
856  *
857  * @param[in]  memory  The memory to compare.
858  *
859  * @param[in]  size  The size of the memory to compare.
860  *
861  * @see check_expected().
862  */
863 void expect_memory(#function, #parameter, void *memory, size_t size);
864 #else
865 #define expect_memory(function, parameter, memory, size) \
866     expect_memory_count(function, parameter, memory, size, 1)
867 #endif
868
869 #ifdef DOXYGEN
870 /**
871  * @brief Add an event to repeatedly check if the parameter does match an area
872  *        of memory.
873  *
874  * The event is triggered by calling check_expected() in the mocked function.
875  *
876  * @param[in]  #function  The function to add the check for.
877  *
878  * @param[in]  #parameter The name of the parameter passed to the function.
879  *
880  * @param[in]  memory  The memory to compare.
881  *
882  * @param[in]  size  The size of the memory to compare.
883  *
884  * @param[in]  count  The count parameter returns the number of times the value
885  *                    should be returned by check_expected(). If count is set
886  *                    to -1 the value will always be returned.
887  *
888  * @see check_expected().
889  */
890 void expect_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
891 #else
892 #define expect_memory_count(function, parameter, memory, size, count) \
893     _expect_memory(#function, #parameter, __FILE__, __LINE__, \
894                    (const void*)(memory), size, count)
895 #endif
896
897 #ifdef DOXYGEN
898 /**
899  * @brief Add an event to check if the parameter doesn't match an area of
900  *        memory.
901  *
902  * The event is triggered by calling check_expected() in the mocked function.
903  *
904  * @param[in]  #function  The function to add the check for.
905  *
906  * @param[in]  #parameter The name of the parameter passed to the function.
907  *
908  * @param[in]  memory  The memory to compare.
909  *
910  * @param[in]  size  The size of the memory to compare.
911  *
912  * @see check_expected().
913  */
914 void expect_not_memory(#function, #parameter, void *memory, size_t size);
915 #else
916 #define expect_not_memory(function, parameter, memory, size) \
917     expect_not_memory_count(function, parameter, memory, size, 1)
918 #endif
919
920 #ifdef DOXYGEN
921 /**
922  * @brief Add an event to repeatedly check if the parameter doesn't match an
923  *        area of memory.
924  *
925  * The event is triggered by calling check_expected() in the mocked function.
926  *
927  * @param[in]  #function  The function to add the check for.
928  *
929  * @param[in]  #parameter The name of the parameter passed to the function.
930  *
931  * @param[in]  memory  The memory to compare.
932  *
933  * @param[in]  size  The size of the memory to compare.
934  *
935  * @param[in]  count  The count parameter returns the number of times the value
936  *                    should be returned by check_expected(). If count is set
937  *                    to -1 the value will always be returned.
938  *
939  * @see check_expected().
940  */
941 void expect_not_memory_count(#function, #parameter, void *memory, size_t size, size_t count);
942 #else
943 #define expect_not_memory_count(function, parameter, memory, size, count) \
944     _expect_not_memory(#function, #parameter, __FILE__, __LINE__, \
945                        (const void*)(memory), size, count)
946 #endif
947
948
949 #ifdef DOXYGEN
950 /**
951  * @brief Add an event to check if a parameter (of any value) has been passed.
952  *
953  * The event is triggered by calling check_expected() in the mocked function.
954  *
955  * @param[in]  #function  The function to add the check for.
956  *
957  * @param[in]  #parameter The name of the parameter passed to the function.
958  *
959  * @see check_expected().
960  */
961 void expect_any(#function, #parameter);
962 #else
963 #define expect_any(function, parameter) \
964     expect_any_count(function, parameter, 1)
965 #endif
966
967 #ifdef DOXYGEN
968 /**
969  * @brief Add an event to repeatedly check if a parameter (of any value) has
970  *        been passed.
971  *
972  * The event is triggered by calling check_expected() in the mocked function.
973  *
974  * @param[in]  #function  The function to add the check for.
975  *
976  * @param[in]  #parameter The name of the parameter passed to the function.
977  *
978  * @param[in]  count  The count parameter returns the number of times the value
979  *                    should be returned by check_expected(). If count is set
980  *                    to -1 the value will always be returned.
981  *
982  * @see check_expected().
983  */
984 void expect_any_count(#function, #parameter, size_t count);
985 #else
986 #define expect_any_count(function, parameter, count) \
987     _expect_any(#function, #parameter, __FILE__, __LINE__, count)
988 #endif
989
990 #ifdef DOXYGEN
991 /**
992  * @brief Determine whether a function parameter is correct.
993  *
994  * This ensures the next value queued by one of the expect_*() macros matches
995  * the specified variable.
996  *
997  * This function needs to be called in the mock object.
998  *
999  * @param[in]  #parameter  The parameter to check.
1000  */
1001 void check_expected(#parameter);
1002 #else
1003 #define check_expected(parameter) \
1004     _check_expected(__func__, #parameter, __FILE__, __LINE__, \
1005                     cast_to_largest_integral_type(parameter))
1006 #endif
1007
1008 #ifdef DOXYGEN
1009 /**
1010  * @brief Determine whether a function parameter is correct.
1011  *
1012  * This ensures the next value queued by one of the expect_*() macros matches
1013  * the specified variable.
1014  *
1015  * This function needs to be called in the mock object.
1016  *
1017  * @param[in]  #parameter  The pointer to check.
1018  */
1019 void check_expected_ptr(#parameter);
1020 #else
1021 #define check_expected_ptr(parameter) \
1022     _check_expected(__func__, #parameter, __FILE__, __LINE__, \
1023                     cast_ptr_to_largest_integral_type(parameter))
1024 #endif
1025
1026 /** @} */
1027
1028 /**
1029  * @defgroup cmocka_asserts Assert Macros
1030  * @ingroup cmocka
1031  *
1032  * This is a set of useful assert macros like the standard C libary's
1033  * assert(3) macro.
1034  *
1035  * On an assertion failure a cmocka assert macro will write the failure to the
1036  * standard error stream and signal a test failure. Due to limitations of the C
1037  * language the general C standard library assert() and cmocka's assert_true()
1038  * and assert_false() macros can only display the expression that caused the
1039  * assert failure. cmocka's type specific assert macros, assert_{type}_equal()
1040  * and assert_{type}_not_equal(), display the data that caused the assertion
1041  * failure which increases data visibility aiding debugging of failing test
1042  * cases.
1043  *
1044  * @{
1045  */
1046
1047 #ifdef DOXYGEN
1048 /**
1049  * @brief Assert that the given expression is true.
1050  *
1051  * The function prints an error message to standard error and terminates the
1052  * test by calling fail() if expression is false (i.e., compares equal to
1053  * zero).
1054  *
1055  * @param[in]  expression  The expression to evaluate.
1056  *
1057  * @see assert_int_equal()
1058  * @see assert_string_equal()
1059  */
1060 void assert_true(scalar expression);
1061 #else
1062 #define assert_true(c) _assert_true(cast_to_largest_integral_type(c), #c, \
1063                                     __FILE__, __LINE__)
1064 #endif
1065
1066 #ifdef DOXYGEN
1067 /**
1068  * @brief Assert that the given expression is false.
1069  *
1070  * The function prints an error message to standard error and terminates the
1071  * test by calling fail() if expression is true.
1072  *
1073  * @param[in]  expression  The expression to evaluate.
1074  *
1075  * @see assert_int_equal()
1076  * @see assert_string_equal()
1077  */
1078 void assert_false(scalar expression);
1079 #else
1080 #define assert_false(c) _assert_true(!(cast_to_largest_integral_type(c)), #c, \
1081                                      __FILE__, __LINE__)
1082 #endif
1083
1084 #ifdef DOXYGEN
1085 /**
1086  * @brief Assert that the return_code is greater than or equal to 0.
1087  *
1088  * The function prints an error message to standard error and terminates the
1089  * test by calling fail() if the return code is smaller than 0. If the function
1090  * you check sets an errno if it fails you can pass it to the function and
1091  * it will be printed as part of the error message.
1092  *
1093  * @param[in]  rc       The return code to evaluate.
1094  *
1095  * @param[in]  error    Pass errno here or 0.
1096  */
1097 void assert_return_code(int rc, int error);
1098 #else
1099 #define assert_return_code(rc, error) \
1100     _assert_return_code(cast_to_largest_integral_type(rc), \
1101                         sizeof(rc), \
1102                         cast_to_largest_integral_type(error), \
1103                         #rc, __FILE__, __LINE__)
1104 #endif
1105
1106 #ifdef DOXYGEN
1107 /**
1108  * @brief Assert that the given pointer is non-NULL.
1109  *
1110  * The function prints an error message to standard error and terminates the
1111  * test by calling fail() if the pointer is NULL.
1112  *
1113  * @param[in]  pointer  The pointer to evaluate.
1114  *
1115  * @see assert_null()
1116  */
1117 void assert_non_null(void *pointer);
1118 #else
1119 #define assert_non_null(c) _assert_true(cast_ptr_to_largest_integral_type(c), #c, \
1120                                         __FILE__, __LINE__)
1121 #endif
1122
1123 #ifdef DOXYGEN
1124 /**
1125  * @brief Assert that the given pointer is NULL.
1126  *
1127  * The function prints an error message to standard error and terminates the
1128  * test by calling fail() if the pointer is non-NULL.
1129  *
1130  * @param[in]  pointer  The pointer to evaluate.
1131  *
1132  * @see assert_non_null()
1133  */
1134 void assert_null(void *pointer);
1135 #else
1136 #define assert_null(c) _assert_true(!(cast_ptr_to_largest_integral_type(c)), #c, \
1137 __FILE__, __LINE__)
1138 #endif
1139
1140 #ifdef DOXYGEN
1141 /**
1142  * @brief Assert that the two given pointers are equal.
1143  *
1144  * The function prints an error message and terminates the test by calling
1145  * fail() if the pointers are not equal.
1146  *
1147  * @param[in]  a        The first pointer to compare.
1148  *
1149  * @param[in]  b        The pointer to compare against the first one.
1150  */
1151 void assert_ptr_equal(void *a, void *b);
1152 #else
1153 #define assert_ptr_equal(a, b) \
1154     _assert_int_equal(cast_ptr_to_largest_integral_type(a), \
1155                       cast_ptr_to_largest_integral_type(b), \
1156                       __FILE__, __LINE__)
1157 #endif
1158
1159 #ifdef DOXYGEN
1160 /**
1161  * @brief Assert that the two given pointers are not equal.
1162  *
1163  * The function prints an error message and terminates the test by calling
1164  * fail() if the pointers are equal.
1165  *
1166  * @param[in]  a        The first pointer to compare.
1167  *
1168  * @param[in]  b        The pointer to compare against the first one.
1169  */
1170 void assert_ptr_not_equal(void *a, void *b);
1171 #else
1172 #define assert_ptr_not_equal(a, b) \
1173     _assert_int_not_equal(cast_ptr_to_largest_integral_type(a), \
1174                           cast_ptr_to_largest_integral_type(b), \
1175                           __FILE__, __LINE__)
1176 #endif
1177
1178 #ifdef DOXYGEN
1179 /**
1180  * @brief Assert that the two given integers are equal.
1181  *
1182  * The function prints an error message to standard error and terminates the
1183  * test by calling fail() if the integers are not equal.
1184  *
1185  * @param[in]  a  The first integer to compare.
1186  *
1187  * @param[in]  b  The integer to compare against the first one.
1188  */
1189 void assert_int_equal(int a, int b);
1190 #else
1191 #define assert_int_equal(a, b) \
1192     _assert_int_equal(cast_to_largest_integral_type(a), \
1193                       cast_to_largest_integral_type(b), \
1194                       __FILE__, __LINE__)
1195 #endif
1196
1197 #ifdef DOXYGEN
1198 /**
1199  * @brief Assert that the two given integers are not equal.
1200  *
1201  * The function prints an error message to standard error and terminates the
1202  * test by calling fail() if the integers are equal.
1203  *
1204  * @param[in]  a  The first integer to compare.
1205  *
1206  * @param[in]  b  The integer to compare against the first one.
1207  *
1208  * @see assert_int_equal()
1209  */
1210 void assert_int_not_equal(int a, int b);
1211 #else
1212 #define assert_int_not_equal(a, b) \
1213     _assert_int_not_equal(cast_to_largest_integral_type(a), \
1214                           cast_to_largest_integral_type(b), \
1215                           __FILE__, __LINE__)
1216 #endif
1217
1218 #ifdef DOXYGEN
1219 /**
1220  * @brief Assert that the two given strings are equal.
1221  *
1222  * The function prints an error message to standard error and terminates the
1223  * test by calling fail() if the strings are not equal.
1224  *
1225  * @param[in]  a  The string to check.
1226  *
1227  * @param[in]  b  The other string to compare.
1228  */
1229 void assert_string_equal(const char *a, const char *b);
1230 #else
1231 #define assert_string_equal(a, b) \
1232     _assert_string_equal((const char*)(a), (const char*)(b), __FILE__, \
1233                          __LINE__)
1234 #endif
1235
1236 #ifdef DOXYGEN
1237 /**
1238  * @brief Assert that the two given strings are not equal.
1239  *
1240  * The function prints an error message to standard error and terminates the
1241  * test by calling fail() if the strings are equal.
1242  *
1243  * @param[in]  a  The string to check.
1244  *
1245  * @param[in]  b  The other string to compare.
1246  */
1247 void assert_string_not_equal(const char *a, const char *b);
1248 #else
1249 #define assert_string_not_equal(a, b) \
1250     _assert_string_not_equal((const char*)(a), (const char*)(b), __FILE__, \
1251                              __LINE__)
1252 #endif
1253
1254 #ifdef DOXYGEN
1255 /**
1256  * @brief Assert that the two given areas of memory are equal, otherwise fail.
1257  *
1258  * The function prints an error message to standard error and terminates the
1259  * test by calling fail() if the memory is not equal.
1260  *
1261  * @param[in]  a  The first memory area to compare
1262  *                (interpreted as unsigned char).
1263  *
1264  * @param[in]  b  The second memory area to compare
1265  *                (interpreted as unsigned char).
1266  *
1267  * @param[in]  size  The first n bytes of the memory areas to compare.
1268  */
1269 void assert_memory_equal(const void *a, const void *b, size_t size);
1270 #else
1271 #define assert_memory_equal(a, b, size) \
1272     _assert_memory_equal((const void*)(a), (const void*)(b), size, __FILE__, \
1273                          __LINE__)
1274 #endif
1275
1276 #ifdef DOXYGEN
1277 /**
1278  * @brief Assert that the two given areas of memory are not equal.
1279  *
1280  * The function prints an error message to standard error and terminates the
1281  * test by calling fail() if the memory is equal.
1282  *
1283  * @param[in]  a  The first memory area to compare
1284  *                (interpreted as unsigned char).
1285  *
1286  * @param[in]  b  The second memory area to compare
1287  *                (interpreted as unsigned char).
1288  *
1289  * @param[in]  size  The first n bytes of the memory areas to compare.
1290  */
1291 void assert_memory_not_equal(const void *a, const void *b, size_t size);
1292 #else
1293 #define assert_memory_not_equal(a, b, size) \
1294     _assert_memory_not_equal((const void*)(a), (const void*)(b), size, \
1295                              __FILE__, __LINE__)
1296 #endif
1297
1298 #ifdef DOXYGEN
1299 /**
1300  * @brief Assert that the specified value is not smaller than the minimum
1301  * and and not greater than the maximum.
1302  *
1303  * The function prints an error message to standard error and terminates the
1304  * test by calling fail() if value is not in range.
1305  *
1306  * @param[in]  value  The value to check.
1307  *
1308  * @param[in]  minimum  The minimum value allowed.
1309  *
1310  * @param[in]  maximum  The maximum value allowed.
1311  */
1312 void assert_in_range(LargestIntegralType value, LargestIntegralType minimum, LargestIntegralType maximum);
1313 #else
1314 #define assert_in_range(value, minimum, maximum) \
1315     _assert_in_range( \
1316         cast_to_largest_integral_type(value), \
1317         cast_to_largest_integral_type(minimum), \
1318         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1319 #endif
1320
1321 #ifdef DOXYGEN
1322 /**
1323  * @brief Assert that the specified value is smaller than the minimum or
1324  * greater than the maximum.
1325  *
1326  * The function prints an error message to standard error and terminates the
1327  * test by calling fail() if value is in range.
1328  *
1329  * @param[in]  value  The value to check.
1330  *
1331  * @param[in]  minimum  The minimum value to compare.
1332  *
1333  * @param[in]  maximum  The maximum value to compare.
1334  */
1335 void assert_not_in_range(LargestIntegralType value, LargestIntegralType minimum, LargestIntegralType maximum);
1336 #else
1337 #define assert_not_in_range(value, minimum, maximum) \
1338     _assert_not_in_range( \
1339         cast_to_largest_integral_type(value), \
1340         cast_to_largest_integral_type(minimum), \
1341         cast_to_largest_integral_type(maximum), __FILE__, __LINE__)
1342 #endif
1343
1344 #ifdef DOXYGEN
1345 /**
1346  * @brief Assert that the specified value is within a set.
1347  *
1348  * The function prints an error message to standard error and terminates the
1349  * test by calling fail() if value is not within a set.
1350  *
1351  * @param[in]  value  The value to look up
1352  *
1353  * @param[in]  values[]  The array to check for the value.
1354  *
1355  * @param[in]  count  The size of the values array.
1356  */
1357 void assert_in_set(LargestIntegralType value, LargestIntegralType values[], size_t count);
1358 #else
1359 #define assert_in_set(value, values, number_of_values) \
1360     _assert_in_set(value, values, number_of_values, __FILE__, __LINE__)
1361 #endif
1362
1363 #ifdef DOXYGEN
1364 /**
1365  * @brief Assert that the specified value is not within a set.
1366  *
1367  * The function prints an error message to standard error and terminates the
1368  * test by calling fail() if value is within a set.
1369  *
1370  * @param[in]  value  The value to look up
1371  *
1372  * @param[in]  values[]  The array to check for the value.
1373  *
1374  * @param[in]  count  The size of the values array.
1375  */
1376 void assert_not_in_set(LargestIntegralType value, LargestIntegralType values[], size_t count);
1377 #else
1378 #define assert_not_in_set(value, values, number_of_values) \
1379     _assert_not_in_set(value, values, number_of_values, __FILE__, __LINE__)
1380 #endif
1381
1382 /** @} */
1383
1384 /**
1385  * @defgroup cmocka_call_order Call Ordering
1386  * @ingroup cmocka
1387  *
1388  * It is often beneficial to  make sure that functions are called in an
1389  * order. This is independent of mock returns and parameter checking as both
1390  * of the aforementioned do not check the order in which they are called from
1391  * different functions.
1392  *
1393  * <ul>
1394  * <li><strong>expect_function_call(function)</strong> - The
1395  * expect_function_call() macro pushes an expectation onto the stack of
1396  * expected calls.</li>
1397  *
1398  * <li><strong>function_called()</strong> - pops a value from the stack of
1399  * expected calls. function_called() is invoked within the mock object
1400  * that uses it.
1401  * </ul>
1402  *
1403  * expect_function_call() and function_called() are intended to be used in
1404  * pairs. Cmocka will fail a test if there are more or less expected calls
1405  * created (e.g. expect_function_call()) than consumed with function_called().
1406  * There are provisions such as ignore_function_calls() which allow this
1407  * restriction to be circumvented in tests where mock calls for the code under
1408  * test are not the focus of the test.
1409  *
1410  * The following example illustrates how a unit test instructs cmocka
1411  * to expect a function_called() from a particular mock,
1412  * <strong>chef_sing()</strong>:
1413  *
1414  * @code
1415  * void chef_sing(void);
1416  *
1417  * void code_under_test()
1418  * {
1419  *   chef_sing();
1420  * }
1421  *
1422  * void some_test(void **state)
1423  * {
1424  *     expect_function_call(chef_sing);
1425  *     code_under_test();
1426  * }
1427  * @endcode
1428  *
1429  * The implementation of the mock then must check whether it was meant to
1430  * be called by invoking <strong>function_called()</strong>:
1431  *
1432  * @code
1433  * void chef_sing()
1434  * {
1435  *     function_called();
1436  * }
1437  * @endcode
1438  *
1439  * @{
1440  */
1441
1442 #ifdef DOXYGEN
1443 /**
1444  * @brief Check that current mocked function is being called in the expected
1445  *        order
1446  *
1447  * @see expect_function_call()
1448  */
1449 void function_called(void);
1450 #else
1451 #define function_called() _function_called(__func__, __FILE__, __LINE__)
1452 #endif
1453
1454 #ifdef DOXYGEN
1455 /**
1456  * @brief Store expected call(s) to a mock to be checked by function_called()
1457  *        later.
1458  *
1459  * @param[in]  #function  The function which should should be called
1460  *
1461  * @param[in]  times number of times this mock must be called
1462  *
1463  * @see function_called()
1464  */
1465 void expect_function_calls(#function, const int times);
1466 #else
1467 #define expect_function_calls(function, times) \
1468     _expect_function_call(#function, __FILE__, __LINE__, times)
1469 #endif
1470
1471 #ifdef DOXYGEN
1472 /**
1473  * @brief Store expected single call to a mock to be checked by
1474  *        function_called() later.
1475  *
1476  * @param[in]  #function  The function which should should be called
1477  *
1478  * @see function_called()
1479  */
1480 void expect_function_call(#function);
1481 #else
1482 #define expect_function_call(function) \
1483     _expect_function_call(#function, __FILE__, __LINE__, 1)
1484 #endif
1485
1486 #ifdef DOXYGEN
1487 /**
1488  * @brief Expects function_called() from given mock at least once
1489  *
1490  * @param[in]  #function  The function which should should be called
1491  *
1492  * @see function_called()
1493  */
1494 void expect_function_call_any(#function);
1495 #else
1496 #define expect_function_call_any(function) \
1497     _expect_function_call(#function, __FILE__, __LINE__, -1)
1498 #endif
1499
1500 #ifdef DOXYGEN
1501 /**
1502  * @brief Ignores function_called() invocations from given mock function.
1503  *
1504  * @param[in]  #function  The function which should should be called
1505  *
1506  * @see function_called()
1507  */
1508 void ignore_function_calls(#function);
1509 #else
1510 #define ignore_function_calls(function) \
1511     _expect_function_call(#function, __FILE__, __LINE__, -2)
1512 #endif
1513
1514 /** @} */
1515
1516 /**
1517  * @defgroup cmocka_exec Running Tests
1518  * @ingroup cmocka
1519  *
1520  * This is the way tests are executed with CMocka.
1521  *
1522  * The following example illustrates this macro's use with the unit_test macro.
1523  *
1524  * @code
1525  * void Test0(void **state);
1526  * void Test1(void **state);
1527  *
1528  * int main(void)
1529  * {
1530  *     const struct CMUnitTest tests[] = {
1531  *         cmocka_unit_test(Test0),
1532  *         cmocka_unit_test(Test1),
1533  *     };
1534  *
1535  *     return cmocka_run_group_tests(tests, NULL, NULL);
1536  * }
1537  * @endcode
1538  *
1539  * @{
1540  */
1541
1542 #ifdef DOXYGEN
1543 /**
1544  * @brief Forces the test to fail immediately and quit.
1545  */
1546 void fail(void);
1547 #else
1548 #define fail() _fail(__FILE__, __LINE__)
1549 #endif
1550
1551 #ifdef DOXYGEN
1552 /**
1553  * @brief Forces the test to not be executed, but marked as skipped
1554  */
1555 void skip(void);
1556 #else
1557 #define skip() _skip(__FILE__, __LINE__)
1558 #endif
1559
1560 #ifdef DOXYGEN
1561 /**
1562  * @brief Forces the test to fail immediately and quit, printing the reason.
1563  *
1564  * @code
1565  * fail_msg("This is some error message for test");
1566  * @endcode
1567  *
1568  * or
1569  *
1570  * @code
1571  * char *error_msg = "This is some error message for test";
1572  * fail_msg("%s", error_msg);
1573  * @endcode
1574  */
1575 void fail_msg(const char *msg, ...);
1576 #else
1577 #define fail_msg(msg, ...) do { \
1578     print_error("ERROR: " msg "\n", ##__VA_ARGS__); \
1579     fail(); \
1580 } while (0)
1581 #endif
1582
1583 #ifdef DOXYGEN
1584 /**
1585  * @brief Generic method to run a single test.
1586  *
1587  * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1588  *
1589  * @param[in]  #function The function to test.
1590  *
1591  * @return 0 on success, 1 if an error occured.
1592  *
1593  * @code
1594  * // A test case that does nothing and succeeds.
1595  * void null_test_success(void **state) {
1596  * }
1597  *
1598  * int main(void) {
1599  *      return run_test(null_test_success);
1600  * }
1601  * @endcode
1602  */
1603 int run_test(#function);
1604 #else
1605 #define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
1606 #endif
1607
1608 static inline void _unit_test_dummy(void **state) {
1609     (void)state;
1610 }
1611
1612 /** Initializes a UnitTest structure.
1613  *
1614  * @deprecated This function was deprecated in favor of cmocka_unit_test
1615  */
1616 #define unit_test(f) { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }
1617
1618 #define _unit_test_setup(test, setup) \
1619     { #test "_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_SETUP }
1620
1621 /** Initializes a UnitTest structure with a setup function.
1622  *
1623  * @deprecated This function was deprecated in favor of cmocka_unit_test_setup
1624  */
1625 #define unit_test_setup(test, setup) \
1626     _unit_test_setup(test, setup), \
1627     unit_test(test), \
1628     _unit_test_teardown(test, _unit_test_dummy)
1629
1630 #define _unit_test_teardown(test, teardown) \
1631     { #test "_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_TEARDOWN }
1632
1633 /** Initializes a UnitTest structure with a teardown function.
1634  *
1635  * @deprecated This function was deprecated in favor of cmocka_unit_test_teardown
1636  */
1637 #define unit_test_teardown(test, teardown) \
1638     _unit_test_setup(test, _unit_test_dummy), \
1639     unit_test(test), \
1640     _unit_test_teardown(test, teardown)
1641
1642 /** Initializes a UnitTest structure for a group setup function.
1643  *
1644  * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1645  */
1646 #define group_test_setup(setup) \
1647     { "group_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP }
1648
1649 /** Initializes a UnitTest structure for a group teardown function.
1650  *
1651  * @deprecated This function was deprecated in favor of cmocka_run_group_tests
1652  */
1653 #define group_test_teardown(teardown) \
1654     { "group_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN }
1655
1656 /**
1657  * Initialize an array of UnitTest structures with a setup function for a test
1658  * and a teardown function.  Either setup or teardown can be NULL.
1659  *
1660  * @deprecated This function was deprecated in favor of
1661  * cmocka_unit_test_setup_teardown
1662  */
1663 #define unit_test_setup_teardown(test, setup, teardown) \
1664     _unit_test_setup(test, setup), \
1665     unit_test(test), \
1666     _unit_test_teardown(test, teardown)
1667
1668
1669 /** Initializes a CMUnitTest structure. */
1670 #define cmocka_unit_test(f) { #f, f, NULL, NULL, NULL }
1671
1672 /** Initializes a CMUnitTest structure with a setup function. */
1673 #define cmocka_unit_test_setup(f, setup) { #f, f, setup, NULL, NULL }
1674
1675 /** Initializes a CMUnitTest structure with a teardown function. */
1676 #define cmocka_unit_test_teardown(f, teardown) { #f, f, NULL, teardown, NULL }
1677
1678 /**
1679  * Initialize an array of CMUnitTest structures with a setup function for a test
1680  * and a teardown function. Either setup or teardown can be NULL.
1681  */
1682 #define cmocka_unit_test_setup_teardown(f, setup, teardown) { #f, f, setup, teardown, NULL }
1683
1684 /**
1685  * Initialize a CMUnitTest structure with given initial state. It will be passed
1686  * to test function as an argument later. It can be used when test state does
1687  * not need special initialization or was initialized already.
1688  * @note If the group setup function initialized the state already, it won't be
1689  * overridden by the initial state defined here.
1690  */
1691 #define cmocka_unit_test_prestate(f, state) { #f, f, NULL, NULL, state }
1692
1693 /**
1694  * Initialize a CMUnitTest structure with given initial state, setup and
1695  * teardown function. Any of these values can be NULL. Initial state is passed
1696  * later to setup function, or directly to test if none was given.
1697  * @note If the group setup function initialized the state already, it won't be
1698  * overridden by the initial state defined here.
1699  */
1700 #define cmocka_unit_test_prestate_setup_teardown(f, setup, teardown, state) { #f, f, setup, teardown, state }
1701
1702 #define run_tests(tests) _run_tests(tests, sizeof(tests) / sizeof((tests)[0]))
1703 #define run_group_tests(tests) _run_group_tests(tests, sizeof(tests) / sizeof((tests)[0]))
1704
1705 #ifdef DOXYGEN
1706 /**
1707  * @brief Run tests specified by an array of CMUnitTest structures.
1708  *
1709  * @param[in]  group_tests[]  The array of unit tests to execute.
1710  *
1711  * @param[in]  group_setup    The setup function which should be called before
1712  *                            all unit tests are executed.
1713  *
1714  * @param[in]  group_teardown The teardown function to be called after all
1715  *                            tests have finished.
1716  *
1717  * @return 0 on success, or the number of failed tests.
1718  *
1719  * @code
1720  * static int setup(void **state) {
1721  *      int *answer = malloc(sizeof(int));
1722  *      if (*answer == NULL) {
1723  *          return -1;
1724  *      }
1725  *      *answer = 42;
1726  *
1727  *      *state = answer;
1728  *
1729  *      return 0;
1730  * }
1731  *
1732  * static int teardown(void **state) {
1733  *      free(*state);
1734  *
1735  *      return 0;
1736  * }
1737  *
1738  * static void null_test_success(void **state) {
1739  *     (void) state;
1740  * }
1741  *
1742  * static void int_test_success(void **state) {
1743  *      int *answer = *state;
1744  *      assert_int_equal(*answer, 42);
1745  * }
1746  *
1747  * int main(void) {
1748  *     const struct CMUnitTest tests[] = {
1749  *         cmocka_unit_test(null_test_success),
1750  *         cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1751  *     };
1752  *
1753  *     return cmocka_run_group_tests(tests, NULL, NULL);
1754  * }
1755  * @endcode
1756  *
1757  * @see cmocka_unit_test
1758  * @see cmocka_unit_test_setup
1759  * @see cmocka_unit_test_teardown
1760  * @see cmocka_unit_test_setup_teardown
1761  */
1762 int cmocka_run_group_tests(const struct CMUnitTest group_tests[],
1763                            CMFixtureFunction group_setup,
1764                            CMFixtureFunction group_teardown);
1765 #else
1766 # define cmocka_run_group_tests(group_tests, group_setup, group_teardown) \
1767         _cmocka_run_group_tests(#group_tests, group_tests, sizeof(group_tests) / sizeof((group_tests)[0]), group_setup, group_teardown)
1768 #endif
1769
1770 #ifdef DOXYGEN
1771 /**
1772  * @brief Run tests specified by an array of CMUnitTest structures and specify
1773  *        a name.
1774  *
1775  * @param[in]  group_name     The name of the group test.
1776  *
1777  * @param[in]  group_tests[]  The array of unit tests to execute.
1778  *
1779  * @param[in]  group_setup    The setup function which should be called before
1780  *                            all unit tests are executed.
1781  *
1782  * @param[in]  group_teardown The teardown function to be called after all
1783  *                            tests have finished.
1784  *
1785  * @return 0 on success, or the number of failed tests.
1786  *
1787  * @code
1788  * static int setup(void **state) {
1789  *      int *answer = malloc(sizeof(int));
1790  *      if (*answer == NULL) {
1791  *          return -1;
1792  *      }
1793  *      *answer = 42;
1794  *
1795  *      *state = answer;
1796  *
1797  *      return 0;
1798  * }
1799  *
1800  * static int teardown(void **state) {
1801  *      free(*state);
1802  *
1803  *      return 0;
1804  * }
1805  *
1806  * static void null_test_success(void **state) {
1807  *     (void) state;
1808  * }
1809  *
1810  * static void int_test_success(void **state) {
1811  *      int *answer = *state;
1812  *      assert_int_equal(*answer, 42);
1813  * }
1814  *
1815  * int main(void) {
1816  *     const struct CMUnitTest tests[] = {
1817  *         cmocka_unit_test(null_test_success),
1818  *         cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
1819  *     };
1820  *
1821  *     return cmocka_run_group_tests_name("success_test", tests, NULL, NULL);
1822  * }
1823  * @endcode
1824  *
1825  * @see cmocka_unit_test
1826  * @see cmocka_unit_test_setup
1827  * @see cmocka_unit_test_teardown
1828  * @see cmocka_unit_test_setup_teardown
1829  */
1830 int cmocka_run_group_tests_name(const char *group_name,
1831                                 const struct CMUnitTest group_tests[],
1832                                 CMFixtureFunction group_setup,
1833                                 CMFixtureFunction group_teardown);
1834 #else
1835 # define cmocka_run_group_tests_name(group_name, group_tests, group_setup, group_teardown) \
1836         _cmocka_run_group_tests(group_name, group_tests, sizeof(group_tests) / sizeof((group_tests)[0]), group_setup, group_teardown)
1837 #endif
1838
1839 /** @} */
1840
1841 /**
1842  * @defgroup cmocka_alloc Dynamic Memory Allocation
1843  * @ingroup cmocka
1844  *
1845  * Memory leaks, buffer overflows and underflows can be checked using cmocka.
1846  *
1847  * To test for memory leaks, buffer overflows and underflows a module being
1848  * tested by cmocka should replace calls to malloc(), calloc() and free() to
1849  * test_malloc(), test_calloc() and test_free() respectively. Each time a block
1850  * is deallocated using test_free() it is checked for corruption, if a corrupt
1851  * block is found a test failure is signalled. All blocks allocated using the
1852  * test_*() allocation functions are tracked by the cmocka library. When a test
1853  * completes if any allocated blocks (memory leaks) remain they are reported
1854  * and a test failure is signalled.
1855  *
1856  * For simplicity cmocka currently executes all tests in one process. Therefore
1857  * all test cases in a test application share a single address space which
1858  * means memory corruption from a single test case could potentially cause the
1859  * test application to exit prematurely.
1860  *
1861  * @{
1862  */
1863
1864 #ifdef DOXYGEN
1865 /**
1866  * @brief Test function overriding malloc.
1867  *
1868  * @param[in]  size  The bytes which should be allocated.
1869  *
1870  * @return A pointer to the allocated memory or NULL on error.
1871  *
1872  * @code
1873  * #ifdef UNIT_TESTING
1874  * extern void* _test_malloc(const size_t size, const char* file, const int line);
1875  *
1876  * #define malloc(size) _test_malloc(size, __FILE__, __LINE__)
1877  * #endif
1878  *
1879  * void leak_memory() {
1880  *     int * const temporary = (int*)malloc(sizeof(int));
1881  *     *temporary = 0;
1882  * }
1883  * @endcode
1884  *
1885  * @see malloc(3)
1886  */
1887 void *test_malloc(size_t size);
1888 #else
1889 #define test_malloc(size) _test_malloc(size, __FILE__, __LINE__)
1890 #endif
1891
1892 #ifdef DOXYGEN
1893 /**
1894  * @brief Test function overriding calloc.
1895  *
1896  * The memory is set to zero.
1897  *
1898  * @param[in]  nmemb  The number of elements for an array to be allocated.
1899  *
1900  * @param[in]  size   The size in bytes of each array element to allocate.
1901  *
1902  * @return A pointer to the allocated memory, NULL on error.
1903  *
1904  * @see calloc(3)
1905  */
1906 void *test_calloc(size_t nmemb, size_t size);
1907 #else
1908 #define test_calloc(num, size) _test_calloc(num, size, __FILE__, __LINE__)
1909 #endif
1910
1911 #ifdef DOXYGEN
1912 /**
1913  * @brief Test function overriding realloc which detects buffer overruns
1914  *        and memoery leaks.
1915  *
1916  * @param[in]  ptr   The memory block which should be changed.
1917  *
1918  * @param[in]  size  The bytes which should be allocated.
1919  *
1920  * @return           The newly allocated memory block, NULL on error.
1921  */
1922 void *test_realloc(void *ptr, size_t size);
1923 #else
1924 #define test_realloc(ptr, size) _test_realloc(ptr, size, __FILE__, __LINE__)
1925 #endif
1926
1927 #ifdef DOXYGEN
1928 /**
1929  * @brief Test function overriding free(3).
1930  *
1931  * @param[in]  ptr  The pointer to the memory space to free.
1932  *
1933  * @see free(3).
1934  */
1935 void test_free(void *ptr);
1936 #else
1937 #define test_free(ptr) _test_free(ptr, __FILE__, __LINE__)
1938 #endif
1939
1940 /* Redirect malloc, calloc and free to the unit test allocators. */
1941 #ifdef UNIT_TESTING
1942 #define malloc test_malloc
1943 #define realloc test_realloc
1944 #define calloc test_calloc
1945 #define free test_free
1946 #endif /* UNIT_TESTING */
1947
1948 /** @} */
1949
1950
1951 /**
1952  * @defgroup cmocka_mock_assert Standard Assertions
1953  * @ingroup cmocka
1954  *
1955  * How to handle assert(3) of the standard C library.
1956  *
1957  * Runtime assert macros like the standard C library's assert() should be
1958  * redefined in modules being tested to use cmocka's mock_assert() function.
1959  * Normally mock_assert() signals a test failure. If a function is called using
1960  * the expect_assert_failure() macro, any calls to mock_assert() within the
1961  * function will result in the execution of the test. If no calls to
1962  * mock_assert() occur during the function called via expect_assert_failure() a
1963  * test failure is signalled.
1964  *
1965  * @{
1966  */
1967
1968 /**
1969  * @brief Function to replace assert(3) in tested code.
1970  *
1971  * In conjuction with check_assert() it's possible to determine whether an
1972  * assert condition has failed without stopping a test.
1973  *
1974  * @param[in]  result  The expression to assert.
1975  *
1976  * @param[in]  expression  The expression as string.
1977  *
1978  * @param[in]  file  The file mock_assert() is called.
1979  *
1980  * @param[in]  line  The line mock_assert() is called.
1981  *
1982  * @code
1983  * #ifdef UNIT_TESTING
1984  * extern void mock_assert(const int result, const char* const expression,
1985  *                         const char * const file, const int line);
1986  *
1987  * #undef assert
1988  * #define assert(expression) \
1989  *     mock_assert((int)(expression), #expression, __FILE__, __LINE__);
1990  * #endif
1991  *
1992  * void increment_value(int * const value) {
1993  *     assert(value);
1994  *     (*value) ++;
1995  * }
1996  * @endcode
1997  *
1998  * @see assert(3)
1999  * @see expect_assert_failure
2000  */
2001 void mock_assert(const int result, const char* const expression,
2002                  const char * const file, const int line);
2003
2004 #ifdef DOXYGEN
2005 /**
2006  * @brief Ensure that mock_assert() is called.
2007  *
2008  * If mock_assert() is called the assert expression string is returned.
2009  *
2010  * @param[in]  fn_call  The function will will call mock_assert().
2011  *
2012  * @code
2013  * #define assert mock_assert
2014  *
2015  * void showmessage(const char *message) {
2016  *   assert(message);
2017  * }
2018  *
2019  * int main(int argc, const char* argv[]) {
2020  *   expect_assert_failure(show_message(NULL));
2021  *   printf("succeeded\n");
2022  *   return 0;
2023  * }
2024  * @endcode
2025  *
2026  */
2027 void expect_assert_failure(function fn_call);
2028 #else
2029 #define expect_assert_failure(function_call) \
2030   { \
2031     const int result = setjmp(global_expect_assert_env); \
2032     global_expecting_assert = 1; \
2033     if (result) { \
2034       print_message("Expected assertion %s occurred\n", \
2035                     global_last_failed_assert); \
2036       global_expecting_assert = 0; \
2037     } else { \
2038       function_call ; \
2039       global_expecting_assert = 0; \
2040       print_error("Expected assert in %s\n", #function_call); \
2041       _fail(__FILE__, __LINE__); \
2042     } \
2043   }
2044 #endif
2045
2046 /** @} */
2047
2048 /* Function prototype for setup, test and teardown functions. */
2049 typedef void (*UnitTestFunction)(void **state);
2050
2051 /* Function that determines whether a function parameter value is correct. */
2052 typedef int (*CheckParameterValue)(const LargestIntegralType value,
2053                                    const LargestIntegralType check_value_data);
2054
2055 /* Type of the unit test function. */
2056 typedef enum UnitTestFunctionType {
2057     UNIT_TEST_FUNCTION_TYPE_TEST = 0,
2058     UNIT_TEST_FUNCTION_TYPE_SETUP,
2059     UNIT_TEST_FUNCTION_TYPE_TEARDOWN,
2060     UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP,
2061     UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN,
2062 } UnitTestFunctionType;
2063
2064 /*
2065  * Stores a unit test function with its name and type.
2066  * NOTE: Every setup function must be paired with a teardown function.  It's
2067  * possible to specify NULL function pointers.
2068  */
2069 typedef struct UnitTest {
2070     const char* name;
2071     UnitTestFunction function;
2072     UnitTestFunctionType function_type;
2073 } UnitTest;
2074
2075 typedef struct GroupTest {
2076     UnitTestFunction setup;
2077     UnitTestFunction teardown;
2078     const UnitTest *tests;
2079     const size_t number_of_tests;
2080 } GroupTest;
2081
2082 /* Function prototype for test functions. */
2083 typedef void (*CMUnitTestFunction)(void **state);
2084
2085 /* Function prototype for setup and teardown functions. */
2086 typedef int (*CMFixtureFunction)(void **state);
2087
2088 struct CMUnitTest {
2089     const char *name;
2090     CMUnitTestFunction test_func;
2091     CMFixtureFunction setup_func;
2092     CMFixtureFunction teardown_func;
2093     void *initial_state;
2094 };
2095
2096 /* Location within some source code. */
2097 typedef struct SourceLocation {
2098     const char* file;
2099     int line;
2100 } SourceLocation;
2101
2102 /* Event that's called to check a parameter value. */
2103 typedef struct CheckParameterEvent {
2104     SourceLocation location;
2105     const char *parameter_name;
2106     CheckParameterValue check_value;
2107     LargestIntegralType check_value_data;
2108 } CheckParameterEvent;
2109
2110 /* Used by expect_assert_failure() and mock_assert(). */
2111 extern int global_expecting_assert;
2112 extern jmp_buf global_expect_assert_env;
2113 extern const char * global_last_failed_assert;
2114
2115 /* Retrieves a value for the given function, as set by "will_return". */
2116 LargestIntegralType _mock(const char * const function, const char* const file,
2117                           const int line);
2118
2119 void _expect_function_call(
2120     const char * const function_name,
2121     const char * const file,
2122     const int line,
2123     const int count);
2124
2125 void _function_called(const char * const function, const char* const file,
2126                           const int line);
2127
2128 void _expect_check(
2129     const char* const function, const char* const parameter,
2130     const char* const file, const int line,
2131     const CheckParameterValue check_function,
2132     const LargestIntegralType check_data, CheckParameterEvent * const event,
2133     const int count);
2134
2135 void _expect_in_set(
2136     const char* const function, const char* const parameter,
2137     const char* const file, const int line, const LargestIntegralType values[],
2138     const size_t number_of_values, const int count);
2139 void _expect_not_in_set(
2140     const char* const function, const char* const parameter,
2141     const char* const file, const int line, const LargestIntegralType values[],
2142     const size_t number_of_values, const int count);
2143
2144 void _expect_in_range(
2145     const char* const function, const char* const parameter,
2146     const char* const file, const int line,
2147     const LargestIntegralType minimum,
2148     const LargestIntegralType maximum, const int count);
2149 void _expect_not_in_range(
2150     const char* const function, const char* const parameter,
2151     const char* const file, const int line,
2152     const LargestIntegralType minimum,
2153     const LargestIntegralType maximum, const int count);
2154
2155 void _expect_value(
2156     const char* const function, const char* const parameter,
2157     const char* const file, const int line, const LargestIntegralType value,
2158     const int count);
2159 void _expect_not_value(
2160     const char* const function, const char* const parameter,
2161     const char* const file, const int line, const LargestIntegralType value,
2162     const int count);
2163
2164 void _expect_string(
2165     const char* const function, const char* const parameter,
2166     const char* const file, const int line, const char* string,
2167     const int count);
2168 void _expect_not_string(
2169     const char* const function, const char* const parameter,
2170     const char* const file, const int line, const char* string,
2171     const int count);
2172
2173 void _expect_memory(
2174     const char* const function, const char* const parameter,
2175     const char* const file, const int line, const void* const memory,
2176     const size_t size, const int count);
2177 void _expect_not_memory(
2178     const char* const function, const char* const parameter,
2179     const char* const file, const int line, const void* const memory,
2180     const size_t size, const int count);
2181
2182 void _expect_any(
2183     const char* const function, const char* const parameter,
2184     const char* const file, const int line, const int count);
2185
2186 void _check_expected(
2187     const char * const function_name, const char * const parameter_name,
2188     const char* file, const int line, const LargestIntegralType value);
2189
2190 void _will_return(const char * const function_name, const char * const file,
2191                   const int line, const LargestIntegralType value,
2192                   const int count);
2193 void _assert_true(const LargestIntegralType result,
2194                   const char* const expression,
2195                   const char * const file, const int line);
2196 void _assert_return_code(const LargestIntegralType result,
2197                          size_t rlen,
2198                          const LargestIntegralType error,
2199                          const char * const expression,
2200                          const char * const file,
2201                          const int line);
2202 void _assert_int_equal(
2203     const LargestIntegralType a, const LargestIntegralType b,
2204     const char * const file, const int line);
2205 void _assert_int_not_equal(
2206     const LargestIntegralType a, const LargestIntegralType b,
2207     const char * const file, const int line);
2208 void _assert_string_equal(const char * const a, const char * const b,
2209                           const char * const file, const int line);
2210 void _assert_string_not_equal(const char * const a, const char * const b,
2211                               const char *file, const int line);
2212 void _assert_memory_equal(const void * const a, const void * const b,
2213                           const size_t size, const char* const file,
2214                           const int line);
2215 void _assert_memory_not_equal(const void * const a, const void * const b,
2216                               const size_t size, const char* const file,
2217                               const int line);
2218 void _assert_in_range(
2219     const LargestIntegralType value, const LargestIntegralType minimum,
2220     const LargestIntegralType maximum, const char* const file, const int line);
2221 void _assert_not_in_range(
2222     const LargestIntegralType value, const LargestIntegralType minimum,
2223     const LargestIntegralType maximum, const char* const file, const int line);
2224 void _assert_in_set(
2225     const LargestIntegralType value, const LargestIntegralType values[],
2226     const size_t number_of_values, const char* const file, const int line);
2227 void _assert_not_in_set(
2228     const LargestIntegralType value, const LargestIntegralType values[],
2229     const size_t number_of_values, const char* const file, const int line);
2230
2231 void* _test_malloc(const size_t size, const char* file, const int line);
2232 void* _test_realloc(void *ptr, const size_t size, const char* file, const int line);
2233 void* _test_calloc(const size_t number_of_elements, const size_t size,
2234                    const char* file, const int line);
2235 void _test_free(void* const ptr, const char* file, const int line);
2236
2237 void _fail(const char * const file, const int line);
2238
2239 void _skip(const char * const file, const int line);
2240
2241 int _run_test(
2242     const char * const function_name, const UnitTestFunction Function,
2243     void ** const volatile state, const UnitTestFunctionType function_type,
2244     const void* const heap_check_point);
2245 CMOCKA_DEPRECATED int _run_tests(const UnitTest * const tests,
2246                                  const size_t number_of_tests);
2247 CMOCKA_DEPRECATED int _run_group_tests(const UnitTest * const tests,
2248                                        const size_t number_of_tests);
2249
2250 /* Test runner */
2251 int _cmocka_run_group_tests(const char *group_name,
2252                             const struct CMUnitTest * const tests,
2253                             const size_t num_tests,
2254                             CMFixtureFunction group_setup,
2255                             CMFixtureFunction group_teardown);
2256
2257 /* Standard output and error print methods. */
2258 void print_message(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2259 void print_error(const char* const format, ...) CMOCKA_PRINTF_ATTRIBUTE(1, 2);
2260 void vprint_message(const char* const format, va_list args) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2261 void vprint_error(const char* const format, va_list args) CMOCKA_PRINTF_ATTRIBUTE(1, 0);
2262
2263 enum cm_message_output {
2264     CM_OUTPUT_STDOUT,
2265     CM_OUTPUT_SUBUNIT,
2266     CM_OUTPUT_TAP,
2267     CM_OUTPUT_XML,
2268 };
2269
2270 /**
2271  * @brief Function to set the output format for a test.
2272  *
2273  * The ouput format for the test can either be set globally using this
2274  * function or overriden with environment variable CMOCKA_MESSAGE_OUTPUT.
2275  *
2276  * The environment variable can be set to either STDOUT, SUBUNIT, TAP or XML.
2277  *
2278  * @param[in] output    The output format to use for the test.
2279  *
2280  */
2281 void cmocka_set_message_output(enum cm_message_output output);
2282
2283
2284 /**
2285  * @brief Set a pattern to only run the test matching the pattern.
2286  *
2287  * This allows to filter tests and only run the ones matching the pattern. Thep
2288  * pattern can include two wildards. The first is '*', a wildcard that matches
2289  * zero or more characters, or ‘?’, a wildcard that matches exactly one
2290  * character.
2291  *
2292  * @param[in]  pattern    The pattern to match, e.g. "test_wurst*"
2293  */
2294 void cmocka_set_test_filter(const char *pattern);
2295
2296 /** @} */
2297
2298 #endif /* CMOCKA_H_ */