test_cleanup_register

(Register a function to run at the end of a TAP test)

SYNOPSIS

#include <tap/basic.h>

typedef void (*test_cleanup_func)(int, int);

void test_cleanup_register(test_cleanup_func func);

DESCRIPTION

test_cleanup_register() registers a cleanup function that is called when testing ends. All such registered functions will be run during atexit handling (and are therefore subject to all the same constraints and caveats as atexit functions). The function must return void and will be passed two arguments, both ints. The first will be true if the test completed successfully and false otherwise. The second will be true if the cleanup function is being run in the primary process (the one in which plan() or plan_lazy() was called) and false otherwise.

Typical uses of cleanup functions include removing temporary files, cleaning up temporary resources, or deciding whether to preserve log files based on whether the test succeeded. Generally, cleanup that involves external resources, like files, should only be done in the primary process (when the second argument is true), but internal resources, like memory, can be freed unconditionally.

test_cleanup_register() may be called at any point in the program before its exit, but either plan() or plan_lazy() must be called before the program exits or cleanup functions will not be run. Provided that plan() or plan_lazy() has been called, the cleanup functions will be called even if the test aborts with bail().

test_cleanup_register() may be called as many times as desired. All registered functions will be called (provided that none of them terminate the process prematurely) in the order in which they were registered.

RETURN VALUE

None.

CAVEATS

Cleanup functions registered with test_cleanup_register() cannot be used to clean up after actions taken before a call to skip_all(), since calling skip_all() means that plan() and plan_lazy() were never called.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

Copyright 2011, 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.

SEE ALSO

plan(3), skip_all(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 2016-11-05 from POD modified 2016-10-26