2 * Basic utility routines for the TAP protocol.
4 * This file is part of C TAP Harness. The current version plus supporting
5 * documentation is at <http://www.eyrie.org/~eagle/software/c-tap-harness/>.
7 * Copyright 2009, 2010, 2011, 2012, 2013 Russ Allbery <eagle@eyrie.org>
8 * Copyright 2001, 2002, 2004, 2005, 2006, 2007, 2008, 2011, 2012, 2014
9 * The Board of Trustees of the Leland Stanford Junior University
11 * Permission is hereby granted, free of charge, to any person obtaining a
12 * copy of this software and associated documentation files (the "Software"),
13 * to deal in the Software without restriction, including without limitation
14 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 * and/or sell copies of the Software, and to permit persons to whom the
16 * Software is furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 * DEALINGS IN THE SOFTWARE.
33 #include <tests/tap/macros.h>
34 #include <stdarg.h> /* va_list */
35 #include <stddef.h> /* size_t */
38 * Used for iterating through arrays. ARRAY_SIZE returns the number of
39 * elements in the array (useful for a < upper bound in a for loop) and
40 * ARRAY_END returns a pointer to the element past the end (ISO C99 makes it
41 * legal to refer to such a pointer as long as it's never dereferenced).
43 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
44 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)])
49 * The test count. Always contains the number that will be used for the next
52 extern unsigned long testnum;
54 /* Print out the number of tests and set standard output to line buffered. */
55 void plan(unsigned long count);
58 * Prepare for lazy planning, in which the plan will be printed automatically
59 * at the end of the test program.
63 /* Skip the entire test suite. Call instead of plan. */
64 void skip_all(const char *format, ...)
65 __attribute__((__noreturn__, __format__(printf, 1, 2)));
68 * Basic reporting functions. The okv() function is the same as ok() but
69 * takes the test description as a va_list to make it easier to reuse the
70 * reporting infrastructure when writing new tests.
72 void ok(int success, const char *format, ...)
73 __attribute__((__format__(printf, 2, 3)));
74 void okv(int success, const char *format, va_list args);
75 void skip(const char *reason, ...)
76 __attribute__((__format__(printf, 1, 2)));
78 /* Report the same status on, or skip, the next count tests. */
79 void ok_block(unsigned long count, int success, const char *format, ...)
80 __attribute__((__format__(printf, 3, 4)));
81 void skip_block(unsigned long count, const char *reason, ...)
82 __attribute__((__format__(printf, 2, 3)));
84 /* Check an expected value against a seen value. */
85 void is_int(long wanted, long seen, const char *format, ...)
86 __attribute__((__format__(printf, 3, 4)));
87 void is_string(const char *wanted, const char *seen, const char *format, ...)
88 __attribute__((__format__(printf, 3, 4)));
89 void is_hex(unsigned long wanted, unsigned long seen, const char *format, ...)
90 __attribute__((__format__(printf, 3, 4)));
92 /* Bail out with an error. sysbail appends strerror(errno). */
93 void bail(const char *format, ...)
94 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
95 void sysbail(const char *format, ...)
96 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
98 /* Report a diagnostic to stderr prefixed with #. */
99 void diag(const char *format, ...)
100 __attribute__((__nonnull__, __format__(printf, 1, 2)));
101 void sysdiag(const char *format, ...)
102 __attribute__((__nonnull__, __format__(printf, 1, 2)));
105 * Register or unregister a file that contains supplementary diagnostics.
106 * Before any other output, all registered files will be read, line by line,
107 * and each line will be reported as a diagnostic as if it were passed to
108 * diag(). Nul characters are not supported in these files and will result in
111 void diag_file_add(const char *file)
112 __attribute__((__nonnull__));
113 void diag_file_remove(const char *file)
114 __attribute__((__nonnull__));
116 /* Allocate memory, reporting a fatal error with bail on failure. */
117 void *bcalloc(size_t, size_t)
118 __attribute__((__alloc_size__(1, 2), __malloc__, __warn_unused_result__));
119 void *bmalloc(size_t)
120 __attribute__((__alloc_size__(1), __malloc__, __warn_unused_result__));
121 void *brealloc(void *, size_t)
122 __attribute__((__alloc_size__(2), __malloc__, __warn_unused_result__));
123 char *bstrdup(const char *)
124 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
125 char *bstrndup(const char *, size_t)
126 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
129 * Find a test file under BUILD or SOURCE, returning the full path. The
130 * returned path should be freed with test_file_path_free().
132 char *test_file_path(const char *file)
133 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
134 void test_file_path_free(char *path);
137 * Create a temporary directory relative to BUILD and return the path. The
138 * returned path should be freed with test_tmpdir_free.
140 char *test_tmpdir(void)
141 __attribute__((__malloc__, __warn_unused_result__));
142 void test_tmpdir_free(char *path);
145 * Register a cleanup function that is called when testing ends. All such
146 * registered functions will be run during atexit handling (and are therefore
147 * subject to all the same constraints and caveats as atexit functions).
149 * The function must return void and will be passed two argument, an int that
150 * will be true if the test completed successfully and false otherwise, and an
151 * int that will be true if the cleanup function is run in the primary process
152 * (the one that called plan or plan_lazy) and false otherwise.
154 typedef void (*test_cleanup_func)(int, int);
155 void test_cleanup_register(test_cleanup_func)
156 __attribute__((__nonnull__));
160 #endif /* TAP_BASIC_H */