1 /* 2 * Basic utility routines for the TAP protocol. 3 * 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/>. 6 * 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 11 * 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: 18 * 19 * The above copyright notice and this permission notice shall be included in 20 * all copies or substantial portions of the Software. 21 * 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. 29 * 30 * SPDX-License-Identifier: MIT 31 */ 32 33 #ifndef TAP_BASIC_H 34 #define TAP_BASIC_H 1 35 36 #include <stdarg.h> /* va_list */ 37 #include <stddef.h> /* size_t */ 38 #include <tests/tap/macros.h> 39 40 /* 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). 45 */ 46 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0])) 47 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)]) 48 49 BEGIN_DECLS 50 51 /* 52 * The test count. Always contains the number that will be used for the next 53 * test status. 54 */ 55 extern unsigned long testnum; 56 57 /* Print out the number of tests and set standard output to line buffered. */ 58 void plan(unsigned long count); 59 60 /* 61 * Prepare for lazy planning, in which the plan will be printed automatically 62 * at the end of the test program. 63 */ 64 void plan_lazy(void); 65 66 /* Skip the entire test suite. Call instead of plan. */ 67 void skip_all(const char *format, ...) 68 __attribute__((__noreturn__, __format__(printf, 1, 2))); 69 70 /* 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. 75 */ 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))); 81 82 /* 83 * Report the same status on, or skip, the next count tests. ok_block() 84 * returns the value of the success argument. 85 */ 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))); 90 91 /* 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 95 * value. 96 */ 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))); 107 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))); 113 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))); 119 120 /* 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 125 * truncated output. 126 */ 127 void diag_file_add(const char *file) __attribute__((__nonnull__)); 128 void diag_file_remove(const char *file) __attribute__((__nonnull__)); 129 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__)); 143 144 /* 145 * Macros that cast the return value from b* memory functions, making them 146 * usable in C++ code and providing some additional type safety. 147 */ 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))) 151 152 /* 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(). 155 */ 156 char *test_file_path(const char *file) 157 __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); 158 void test_file_path_free(char *path); 159 160 /* 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(). 163 */ 164 char *test_tmpdir(void) __attribute__((__malloc__, __warn_unused_result__)); 165 void test_tmpdir_free(char *path); 166 167 /* 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). 171 * 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. 178 * 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 181 * cmpatibility. 182 */ 183 typedef void (*test_cleanup_func)(int, int); 184 typedef void (*test_cleanup_func_with_data)(int, int, void *); 185 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__)); 189 190 END_DECLS 191 192 #endif /* TAP_BASIC_H */ 193