include/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
  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 ouput 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_ */