1 /* $Id: basic.h 10396 2020-11-12 20:19:41Z iulius $ 2 * 3 * Basic utility routines for the TAP protocol. 4 * 5 * This file is part of C TAP Harness. The current version plus supporting 6 * documentation is at <https://www.eyrie.org/~eagle/software/c-tap-harness/>. 7 * 8 * Written by Russ Allbery <eagle@eyrie.org> 9 * Copyright 2009-2019 Russ Allbery <eagle@eyrie.org> 10 * Copyright 2001-2002, 2004-2008, 2011-2012, 2014 11 * The Board of Trustees of the Leland Stanford Junior University 12 * 13 * Permission is hereby granted, free of charge, to any person obtaining a 14 * copy of this software and associated documentation files (the "Software"), 15 * to deal in the Software without restriction, including without limitation 16 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 17 * and/or sell copies of the Software, and to permit persons to whom the 18 * Software is furnished to do so, subject to the following conditions: 19 * 20 * The above copyright notice and this permission notice shall be included in 21 * all copies or substantial portions of the Software. 22 * 23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 26 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 28 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 29 * DEALINGS IN THE SOFTWARE. 30 * 31 * SPDX-License-Identifier: MIT 32 */ 33 34 #ifndef TAP_BASIC_H 35 #define TAP_BASIC_H 1 36 37 #include <stdarg.h> /* va_list */ 38 #include <stddef.h> /* size_t */ 39 #include <tap/macros.h> 40 41 /* 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). 46 */ 47 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0])) 48 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)]) 49 50 BEGIN_DECLS 51 52 /* 53 * The test count. Always contains the number that will be used for the next 54 * test status. 55 */ 56 extern unsigned long testnum; 57 58 /* Print out the number of tests and set standard output to line buffered. */ 59 void plan(unsigned long count); 60 61 /* 62 * Prepare for lazy planning, in which the plan will be printed automatically 63 * at the end of the test program. 64 */ 65 void plan_lazy(void); 66 67 /* Skip the entire test suite. Call instead of plan. */ 68 void skip_all(const char *format, ...) 69 __attribute__((__noreturn__, __format__(printf, 1, 2))); 70 71 /* 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. 76 */ 77 #ifndef LIBTEST_NEW_FORMAT 78 /* Specific to the integration of C TAP Harness in INN. */ 79 void ok(int n, int success); 80 int new_ok(int success, const char *format, ...) 81 __attribute__((__format__(printf, 2, 3))); 82 void ok_int(int n, int wanted, int seen); 83 void ok_string(int n, const char *wanted, const char *seen); 84 int okv(int success, const char *format, va_list args) 85 __attribute__((__format__(printf, 2, 0))); 86 void skip(int n, const char *reason); 87 void new_skip(const char *reason, ...) 88 __attribute__((__format__(printf, 1, 2))); 89 void ok_block(int n, int count, int success); 90 int new_ok_block(unsigned long count, int success, const char *format, ...) 91 __attribute__((__format__(printf, 3, 4))); 92 void skip_block(int n, int count, const char *reason); 93 void new_skip_block(unsigned long count, const char *reason, ...) 94 __attribute__((__format__(printf, 2, 3))); 95 96 void test_init(int count); 97 #else 98 # define ok new_ok 99 # define skip new_skip 100 # define ok_block new_ok_block 101 # define skip_block new_skip_block 102 int ok(int success, const char *format, ...) 103 __attribute__((__format__(printf, 2, 3))); 104 int okv(int success, const char *format, va_list args) 105 __attribute__((__format__(printf, 2, 0))); 106 void skip(const char *reason, ...) __attribute__((__format__(printf, 1, 2))); 107 108 /* 109 * Report the same status on, or skip, the next count tests. ok_block() 110 * returns the value of the success argument. 111 */ 112 int ok_block(unsigned long count, int success, const char *format, ...) 113 __attribute__((__format__(printf, 3, 4))); 114 void skip_block(unsigned long count, const char *reason, ...) 115 __attribute__((__format__(printf, 2, 3))); 116 117 #endif 118 /* 119 * Compare two values. Returns true if the test passes and false if it fails. 120 * is_bool takes an int since the bool type isn't fully portable yet, but 121 * interprets both arguments for their truth value, not for their numeric 122 * value. 123 */ 124 int is_bool(int, int, const char *format, ...) 125 __attribute__((__format__(printf, 3, 4))); 126 int is_int(long, long, const char *format, ...) 127 __attribute__((__format__(printf, 3, 4))); 128 int is_string(const char *, const char *, const char *format, ...) 129 __attribute__((__format__(printf, 3, 4))); 130 int is_hex(unsigned long, unsigned long, const char *format, ...) 131 __attribute__((__format__(printf, 3, 4))); 132 int is_blob(const void *, const void *, size_t, const char *format, ...) 133 __attribute__((__format__(printf, 4, 5))); 134 135 /* Bail out with an error. sysbail appends strerror(errno). */ 136 void bail(const char *format, ...) 137 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2))); 138 void sysbail(const char *format, ...) 139 __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2))); 140 141 /* Report a diagnostic to stderr prefixed with #. */ 142 int diag(const char *format, ...) 143 __attribute__((__nonnull__, __format__(printf, 1, 2))); 144 int sysdiag(const char *format, ...) 145 __attribute__((__nonnull__, __format__(printf, 1, 2))); 146 147 /* 148 * Register or unregister a file that contains supplementary diagnostics. 149 * Before any other output, all registered files will be read, line by line, 150 * and each line will be reported as a diagnostic as if it were passed to 151 * diag(). Nul characters are not supported in these files and will result in 152 * truncated output. 153 */ 154 void diag_file_add(const char *file) __attribute__((__nonnull__)); 155 void diag_file_remove(const char *file) __attribute__((__nonnull__)); 156 157 /* Allocate memory, reporting a fatal error with bail on failure. */ 158 void *bcalloc(size_t, size_t) 159 __attribute__((__alloc_size__(1, 2), __malloc__, __warn_unused_result__)); 160 void *bmalloc(size_t) 161 __attribute__((__alloc_size__(1), __malloc__, __warn_unused_result__)); 162 void *breallocarray(void *, size_t, size_t) 163 __attribute__((__alloc_size__(2, 3), __malloc__, __warn_unused_result__)); 164 void *brealloc(void *, size_t) 165 __attribute__((__alloc_size__(2), __malloc__, __warn_unused_result__)); 166 char *bstrdup(const char *) 167 __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); 168 char *bstrndup(const char *, size_t) 169 __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); 170 171 /* 172 * Macros that cast the return value from b* memory functions, making them 173 * usable in C++ code and providing some additional type safety. 174 */ 175 #define bcalloc_type(n, type) ((type *) bcalloc((n), sizeof(type))) 176 #define breallocarray_type(p, n, type) \ 177 ((type *) breallocarray((p), (n), sizeof(type))) 178 179 /* 180 * Find a test file under C_TAP_BUILD or C_TAP_SOURCE, returning the full 181 * path. The returned path should be freed with test_file_path_free(). 182 */ 183 char *test_file_path(const char *file) 184 __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); 185 void test_file_path_free(char *path); 186 187 /* 188 * Create a temporary directory relative to C_TAP_BUILD and return the path. 189 * The returned path should be freed with test_tmpdir_free(). 190 */ 191 char *test_tmpdir(void) __attribute__((__malloc__, __warn_unused_result__)); 192 void test_tmpdir_free(char *path); 193 194 /* 195 * Register a cleanup function that is called when testing ends. All such 196 * registered functions will be run during atexit handling (and are therefore 197 * subject to all the same constraints and caveats as atexit functions). 198 * 199 * The function must return void and will be passed two arguments: an int that 200 * will be true if the test completed successfully and false otherwise, and an 201 * int that will be true if the cleanup function is run in the primary process 202 * (the one that called plan or plan_lazy) and false otherwise. If 203 * test_cleanup_register_with_data is used instead, a generic pointer can be 204 * provided and will be passed to the cleanup function as a third argument. 205 * 206 * test_cleanup_register_with_data is the better API and should have been the 207 * only API. test_cleanup_register was an API error preserved for backward 208 * cmpatibility. 209 */ 210 typedef void (*test_cleanup_func)(int, int); 211 typedef void (*test_cleanup_func_with_data)(int, int, void *); 212 213 void test_cleanup_register(test_cleanup_func) __attribute__((__nonnull__)); 214 void test_cleanup_register_with_data(test_cleanup_func_with_data, void *) 215 __attribute__((__nonnull__)); 216 217 END_DECLS 218 219 #endif /* TAP_BASIC_H */ 220