Import of code from c-tap-harness
[openafs.git] / src / external / c-tap-harness / tests / tap / basic.h
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 */