### 6.4 C unit testing API ¶

The C API is provided in the `dejagnu.h` header file. This header provides a self-contained implementation. For convenience, the `totals()` function can be called at the end of the unit test program to output summary totals. DejaGnu counts the test results independently and will operate correctly even if `totals()` is never invoked.

All of the functions that take a `msg` parameter use a C `char *` that is the message to be displayed. All of the functions that display a message accept a `printf`-style format string and variable arguments.

- `note` emits a note that will be displayed at verbose level 2 or higher.

  > `note(msg, ...);`

- `pass` prints a message for a successful test completion.

  > `pass(msg, ...);`

- `fail` prints a message for an unsuccessful test completion.

  > `fail(msg, ...);`

- `xfail` prints a message for an expected unsuccessful test completion.

  > `xfail(msg, ...);`

- `xpass` prints a message for an unexpected successful test completion.

  > `xpass(msg, ...);`

- `untested` prints a placeholder message for a test case that is not yet implemented or that could not be run for some reason.

  > `untested(msg, ...);`

- `unresolved` prints a message for a test case that was run, but did not produce a clear result. These output states require a human to look over the results to determine what happened.

  > `unresolved(msg, ...);`

- `totals` prints out the total counts of all of the test results as a convenience when running the unit test program directly. DejaGnu does not use this information and instead counts the results independently.

  > `totals();`