diag, sysdiag

(Report diagnostics in a TAP test case)

SYNOPSIS

#include <tap/basic.h>

int diag(const char *format, ...);

int sysdiag(const char *format, ...);

DESCRIPTION

diag() reports a diagnostic in a TAP test case. format must be a printf-style format string with possible optional arguments stating the fatal error encountered. This function adds # and a space to the beginning of the formatted string and prints it, followed by a newline, to standard output.

sysdiag() is identical to diag() except that it appends a colon, a space, and the results of strerror() on the current value of errno to the end of the diagnostic.

These functions are useful for reporting supplemental information about the progress of a test case or additional information about test failures. The output will be ignored by a TAP test harness but can be reviewed by a human analyzing what a test case is doing.

RETURN VALUE

diag() and sysdiag() always return 1. The return value is not meaningful, and exists only to allow these functions to be dropped into the middle of compound statements, allowing debugging of tests without more intrusive changes.

CAVEATS

Unlike most TAP library functions, format in this case may not be NULL. A diagnostic message must be provided.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

Copyright 2010, 2013-2014 Russ Allbery <eagle@eyrie.org>

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

SPDX-License-Identifier: FSFAP

SEE ALSO

bail(3), plan(3)

The current version of the C TAP Harness library is available from its web page at <https://www.eyrie.org/~eagle/software/c-tap-harness/>.

Last spun 2022-12-12 from POD modified 2018-01-16