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