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 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 <tests/tap/macros.h>
41 * Used for iterating through arrays. ARRAY_SIZE returns the number of
42 * elements in the array (useful for a < upper bound in a for loop) and
43 * ARRAY_END returns a pointer to the element past the end (ISO C99 makes it
44 * legal to refer to such a pointer as long as it's never dereferenced).
46 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
47 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)])
52 * The test count. Always contains the number that will be used for the next
55 extern unsigned long testnum;
57 /* Print out the number of tests and set standard output to line buffered. */
58 void plan(unsigned long count);
61 * Prepare for lazy planning, in which the plan will be printed automatically
62 * at the end of the test program.
66 /* Skip the entire test suite. Call instead of plan. */
67 void skip_all(const char *format, ...)
68 __attribute__((__noreturn__, __format__(printf, 1, 2)));
71 * Basic reporting functions. The okv() function is the same as ok() but
72 * takes the test description as a va_list to make it easier to reuse the
73 * reporting infrastructure when writing new tests. ok() and okv() return the
74 * value of the success argument.
76 int ok(int success, const char *format, ...)
77 __attribute__((__format__(printf, 2, 3)));
78 int okv(int success, const char *format, va_list args)
79 __attribute__((__format__(printf, 2, 0)));
80 void skip(const char *reason, ...) __attribute__((__format__(printf, 1, 2)));
83 * Report the same status on, or skip, the next count tests. ok_block()
84 * returns the value of the success argument.
86 int ok_block(unsigned long count, int success, const char *format, ...)
87 __attribute__((__format__(printf, 3, 4)));
88 void skip_block(unsigned long count, const char *reason, ...)
89 __attribute__((__format__(printf, 2, 3)));
92 * Compare two values. Returns true if the test passes and false if it fails.
93 * is_bool takes an int since the bool type isn't fully portable yet, but
94 * interprets both arguments for their truth value, not for their numeric
97 int is_bool(int, int, const char *format, ...)
98 __attribute__((__format__(printf, 3, 4)));
99 int is_int(long, long, const char *format, ...)
100 __attribute__((__format__(printf, 3, 4)));
101 int is_string(const char *, const char *, const char *format, ...)
102 __attribute__((__format__(printf, 3, 4)));
103 int is_hex(unsigned long, unsigned long, const char *format, ...)
104 __attribute__((__format__(printf, 3, 4)));
105 int is_blob(const void *, const void *, size_t, const char *format, ...)
106 __attribute__((__format__(printf, 4, 5)));
108 /* Bail out with an error. sysbail appends strerror(errno). */
109 void bail(const char *format, ...)
110 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
111 void sysbail(const char *format, ...)
112 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2)));
114 /* Report a diagnostic to stderr prefixed with #. */
115 int diag(const char *format, ...)
116 __attribute__((__nonnull__, __format__(printf, 1, 2)));
117 int sysdiag(const char *format, ...)
118 __attribute__((__nonnull__, __format__(printf, 1, 2)));
121 * Register or unregister a file that contains supplementary diagnostics.
122 * Before any other output, all registered files will be read, line by line,
123 * and each line will be reported as a diagnostic as if it were passed to
124 * diag(). Nul characters are not supported in these files and will result in
127 void diag_file_add(const char *file) __attribute__((__nonnull__));
128 void diag_file_remove(const char *file) __attribute__((__nonnull__));
130 /* Allocate memory, reporting a fatal error with bail on failure. */
131 void *bcalloc(size_t, size_t)
132 __attribute__((__alloc_size__(1, 2), __malloc__, __warn_unused_result__));
133 void *bmalloc(size_t)
134 __attribute__((__alloc_size__(1), __malloc__, __warn_unused_result__));
135 void *breallocarray(void *, size_t, size_t)
136 __attribute__((__alloc_size__(2, 3), __malloc__, __warn_unused_result__));
137 void *brealloc(void *, size_t)
138 __attribute__((__alloc_size__(2), __malloc__, __warn_unused_result__));
139 char *bstrdup(const char *)
140 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
141 char *bstrndup(const char *, size_t)
142 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
145 * Macros that cast the return value from b* memory functions, making them
146 * usable in C++ code and providing some additional type safety.
148 #define bcalloc_type(n, type) ((type *) bcalloc((n), sizeof(type)))
149 #define breallocarray_type(p, n, type) \
150 ((type *) breallocarray((p), (n), sizeof(type)))
153 * Find a test file under C_TAP_BUILD or C_TAP_SOURCE, returning the full
154 * path. The returned path should be freed with test_file_path_free().
156 char *test_file_path(const char *file)
157 __attribute__((__malloc__, __nonnull__, __warn_unused_result__));
158 void test_file_path_free(char *path);
161 * Create a temporary directory relative to C_TAP_BUILD and return the path.
162 * The returned path should be freed with test_tmpdir_free().
164 char *test_tmpdir(void) __attribute__((__malloc__, __warn_unused_result__));
165 void test_tmpdir_free(char *path);
168 * Register a cleanup function that is called when testing ends. All such
169 * registered functions will be run during atexit handling (and are therefore
170 * subject to all the same constraints and caveats as atexit functions).
172 * The function must return void and will be passed two arguments: an int that
173 * will be true if the test completed successfully and false otherwise, and an
174 * int that will be true if the cleanup function is run in the primary process
175 * (the one that called plan or plan_lazy) and false otherwise. If
176 * test_cleanup_register_with_data is used instead, a generic pointer can be
177 * provided and will be passed to the cleanup function as a third argument.
179 * test_cleanup_register_with_data is the better API and should have been the
180 * only API. test_cleanup_register was an API error preserved for backward
183 typedef void (*test_cleanup_func)(int, int);
184 typedef void (*test_cleanup_func_with_data)(int, int, void *);
186 void test_cleanup_register(test_cleanup_func) __attribute__((__nonnull__));
187 void test_cleanup_register_with_data(test_cleanup_func_with_data, void *)
188 __attribute__((__nonnull__));
192 #endif /* TAP_BASIC_H */