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 <https://www.eyrie.org/~eagle/software/c-tap-harness/>.
7 * Written by Russ Allbery <eagle@eyrie.org>
8 * Copyright 2009-2019, 2022 Russ Allbery <eagle@eyrie.org>
9 * Copyright 2001-2002, 2004-2008, 2011-2012, 2014
10 * The Board of Trustees of the Leland Stanford Junior University
12 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 * DEALINGS IN THE SOFTWARE.
30 * SPDX-License-Identifier: MIT
36 #include <stdarg.h> /* va_list */
37 #include <stddef.h> /* size_t */
38 #include <stdlib.h> /* free */
39 #include <tests/tap/macros.h>
42 * Used for iterating through arrays. ARRAY_SIZE returns the number of
43 * elements in the array (useful for a < upper bound in a for loop) and
44 * ARRAY_END returns a pointer to the element past the end (ISO C99 makes it
45 * legal to refer to such a pointer as long as it's never dereferenced).
47 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
48 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)])
53 * The test count. Always contains the number that will be used for the next
56 extern unsigned long testnum;
58 /* Print out the number of tests and set standard output to line buffered. */
59 void plan(unsigned long count);
62 * Prepare for lazy planning, in which the plan will be printed automatically
63 * at the end of the test program.
67 /* Skip the entire test suite. Call instead of plan. */
68 void skip_all(const char *format, ...)
69 __attribute__((__noreturn__, __format__(printf, 1, 2)));
72 * Basic reporting functions. The okv() function is the same as ok() but
73 * takes the test description as a va_list to make it easier to reuse the
74 * reporting infrastructure when writing new tests. ok() and okv() return the
75 * value of the success argument.
77 int ok(int success, const char *format, ...)
78 __attribute__((__format__(printf, 2, 3)));
79 int okv(int success, const char *format, va_list args)
80 __attribute__((__format__(printf, 2, 0)));
81 void skip(const char *reason, ...) __attribute__((__format__(printf, 1, 2)));
84 * Report the same status on, or skip, the next count tests. ok_block()
85 * returns the value of the success argument.
87 int ok_block(unsigned long count, int success, const char *format, ...)
88 __attribute__((__format__(printf, 3, 4)));
89 void skip_block(unsigned long count, const char *reason, ...)
90 __attribute__((__format__(printf, 2, 3)));
93 * Compare two values. Returns true if the test passes and false if it fails.
94 * is_bool takes an int since the bool type isn't fully portable yet, but
95 * interprets both arguments for their truth value, not for their numeric
98 int is_bool(int, int, const char *format, ...)
99 __attribute__((__format__(printf, 3, 4)));
100 int is_int(long, long, const char *format, ...)
101 __attribute__((__format__(printf, 3, 4)));
102 int is_string(const char *, const char *, const char *format, ...)
103 __attribute__((__format__(printf, 3, 4)));
104 int is_hex(unsigned long, unsigned long, const char *format, ...)
105 __attribute__((__format__(printf, 3, 4)));
106 int is_blob(const void *, const void *, size_t, const char *format, ...)
107 __attribute__((__format__(printf, 4, 5)));
109 /* Bail out with an error. sysbail appends strerror(errno). */
110 void bail(const char *format, ...)
111 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
112 void sysbail(const char *format, ...)
113 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
115 /* Report a diagnostic to stderr prefixed with #. */
116 int diag(const char *format, ...)
117 __attribute__((__nonnull__, __format__(printf, 1, 2)));
118 int sysdiag(const char *format, ...)
119 __attribute__((__nonnull__, __format__(printf, 1, 2)));
122 * Register or unregister a file that contains supplementary diagnostics.
123 * Before any other output, all registered files will be read, line by line,
124 * and each line will be reported as a diagnostic as if it were passed to
125 * diag(). Nul characters are not supported in these files and will result in
128 void diag_file_add(const char *file) __attribute__((__nonnull__));
129 void diag_file_remove(const char *file) __attribute__((__nonnull__));
131 /* Allocate memory, reporting a fatal error with bail on failure. */
132 void *bcalloc(size_t, size_t)
133 __attribute__((__alloc_size__(1, 2), __malloc__(free),
134 __warn_unused_result__));
135 void *bmalloc(size_t) __attribute__((__alloc_size__(1), __malloc__(free),
136 __warn_unused_result__));
137 void *breallocarray(void *, size_t, size_t)
138 __attribute__((__alloc_size__(2, 3), __malloc__(free),
139 __warn_unused_result__));
140 void *brealloc(void *, size_t)
141 __attribute__((__alloc_size__(2), __malloc__(free),
142 __warn_unused_result__));
143 char *bstrdup(const char *)
144 __attribute__((__malloc__(free), __nonnull__, __warn_unused_result__));
145 char *bstrndup(const char *, size_t)
146 __attribute__((__malloc__(free), __nonnull__, __warn_unused_result__));
149 * Macros that cast the return value from b* memory functions, making them
150 * usable in C++ code and providing some additional type safety.
152 #define bcalloc_type(n, type) ((type *) bcalloc((n), sizeof(type)))
153 #define breallocarray_type(p, n, type) \
154 ((type *) breallocarray((p), (n), sizeof(type)))
157 * Find a test file under C_TAP_BUILD or C_TAP_SOURCE, returning the full
158 * path. The returned path should be freed with test_file_path_free().
160 void test_file_path_free(char *path);
161 char *test_file_path(const char *file)
162 __attribute__((__malloc__(test_file_path_free), __nonnull__,
163 __warn_unused_result__));
166 * Create a temporary directory relative to C_TAP_BUILD and return the path.
167 * The returned path should be freed with test_tmpdir_free().
169 void test_tmpdir_free(char *path);
170 char *test_tmpdir(void)
171 __attribute__((__malloc__(test_tmpdir_free), __warn_unused_result__));
174 * Register a cleanup function that is called when testing ends. All such
175 * registered functions will be run during atexit handling (and are therefore
176 * subject to all the same constraints and caveats as atexit functions).
178 * The function must return void and will be passed two arguments: an int that
179 * will be true if the test completed successfully and false otherwise, and an
180 * int that will be true if the cleanup function is run in the primary process
181 * (the one that called plan or plan_lazy) and false otherwise. If
182 * test_cleanup_register_with_data is used instead, a generic pointer can be
183 * provided and will be passed to the cleanup function as a third argument.
185 * test_cleanup_register_with_data is the better API and should have been the
186 * only API. test_cleanup_register was an API error preserved for backward
189 typedef void (*test_cleanup_func)(int, int);
190 typedef void (*test_cleanup_func_with_data)(int, int, void *);
192 void test_cleanup_register(test_cleanup_func) __attribute__((__nonnull__));
193 void test_cleanup_register_with_data(test_cleanup_func_with_data, void *)
194 __attribute__((__nonnull__));
198 #endif /* TAP_BASIC_H */