]>
Commit | Line | Data |
---|---|---|
8fe5ef5a SA |
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 | * Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 | |
8 | * Russ Allbery <eagle@eyrie.org> | |
9 | * Copyright 2001, 2002, 2004, 2005, 2006, 2007, 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 | ||
31 | #ifndef TAP_BASIC_H | |
32 | #define TAP_BASIC_H 1 | |
33 | ||
34 | #include <tests/tap/macros.h> | |
35 | #include <stdarg.h> /* va_list */ | |
36 | #include <stddef.h> /* size_t */ | |
37 | ||
38 | /* | |
39 | * Used for iterating through arrays. ARRAY_SIZE returns the number of | |
40 | * elements in the array (useful for a < upper bound in a for loop) and | |
41 | * ARRAY_END returns a pointer to the element past the end (ISO C99 makes it | |
42 | * legal to refer to such a pointer as long as it's never dereferenced). | |
43 | */ | |
44 | #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0])) | |
45 | #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)]) | |
46 | ||
47 | BEGIN_DECLS | |
48 | ||
49 | /* | |
50 | * The test count. Always contains the number that will be used for the next | |
51 | * test status. | |
52 | */ | |
53 | extern unsigned long testnum; | |
54 | ||
55 | /* Print out the number of tests and set standard output to line buffered. */ | |
56 | void plan(unsigned long count); | |
57 | ||
58 | /* | |
59 | * Prepare for lazy planning, in which the plan will be printed automatically | |
60 | * at the end of the test program. | |
61 | */ | |
62 | void plan_lazy(void); | |
63 | ||
64 | /* Skip the entire test suite. Call instead of plan. */ | |
65 | void skip_all(const char *format, ...) | |
66 | __attribute__((__noreturn__, __format__(printf, 1, 2))); | |
67 | ||
68 | /* | |
69 | * Basic reporting functions. The okv() function is the same as ok() but | |
70 | * takes the test description as a va_list to make it easier to reuse the | |
71 | * reporting infrastructure when writing new tests. ok() and okv() return the | |
72 | * value of the success argument. | |
73 | */ | |
74 | int ok(int success, const char *format, ...) | |
75 | __attribute__((__format__(printf, 2, 3))); | |
76 | int okv(int success, const char *format, va_list args) | |
77 | __attribute__((__format__(printf, 2, 0))); | |
78 | void skip(const char *reason, ...) | |
79 | __attribute__((__format__(printf, 1, 2))); | |
80 | ||
81 | /* | |
82 | * Report the same status on, or skip, the next count tests. ok_block() | |
83 | * returns the value of the success argument. | |
84 | */ | |
85 | int ok_block(unsigned long count, int success, const char *format, ...) | |
86 | __attribute__((__format__(printf, 3, 4))); | |
87 | void skip_block(unsigned long count, const char *reason, ...) | |
88 | __attribute__((__format__(printf, 2, 3))); | |
89 | ||
90 | /* | |
91 | * Check an expected value against a seen value. Returns true if the test | |
92 | * passes and false if it fails. is_bool takes an int since the bool type | |
93 | * isn't fully portable yet, but interprets both arguments for their truth | |
94 | * value, not for their numeric value. | |
95 | */ | |
96 | int is_bool(int wanted, int seen, const char *format, ...) | |
97 | __attribute__((__format__(printf, 3, 4))); | |
98 | int is_int(long wanted, long seen, const char *format, ...) | |
99 | __attribute__((__format__(printf, 3, 4))); | |
100 | int is_string(const char *wanted, const char *seen, const char *format, ...) | |
101 | __attribute__((__format__(printf, 3, 4))); | |
102 | int is_hex(unsigned long wanted, unsigned long seen, const char *format, ...) | |
103 | __attribute__((__format__(printf, 3, 4))); | |
104 | ||
105 | /* Bail out with an error. sysbail appends strerror(errno). */ | |
106 | void bail(const char *format, ...) | |
107 | __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2))); | |
108 | void sysbail(const char *format, ...) | |
109 | __attribute__((__noreturn__, __nonnull__, __format__(printf, 1, 2))); | |
110 | ||
111 | /* Report a diagnostic to stderr prefixed with #. */ | |
112 | int diag(const char *format, ...) | |
113 | __attribute__((__nonnull__, __format__(printf, 1, 2))); | |
114 | int sysdiag(const char *format, ...) | |
115 | __attribute__((__nonnull__, __format__(printf, 1, 2))); | |
116 | ||
117 | /* | |
118 | * Register or unregister a file that contains supplementary diagnostics. | |
119 | * Before any other output, all registered files will be read, line by line, | |
120 | * and each line will be reported as a diagnostic as if it were passed to | |
121 | * diag(). Nul characters are not supported in these files and will result in | |
122 | * truncated output. | |
123 | */ | |
124 | void diag_file_add(const char *file) | |
125 | __attribute__((__nonnull__)); | |
126 | void diag_file_remove(const char *file) | |
127 | __attribute__((__nonnull__)); | |
128 | ||
129 | /* Allocate memory, reporting a fatal error with bail on failure. */ | |
130 | void *bcalloc(size_t, size_t) | |
131 | __attribute__((__alloc_size__(1, 2), __malloc__, __warn_unused_result__)); | |
132 | void *bmalloc(size_t) | |
133 | __attribute__((__alloc_size__(1), __malloc__, __warn_unused_result__)); | |
134 | void *breallocarray(void *, size_t, size_t) | |
135 | __attribute__((__alloc_size__(2, 3), __malloc__, __warn_unused_result__)); | |
136 | void *brealloc(void *, size_t) | |
137 | __attribute__((__alloc_size__(2), __malloc__, __warn_unused_result__)); | |
138 | char *bstrdup(const char *) | |
139 | __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); | |
140 | char *bstrndup(const char *, size_t) | |
141 | __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); | |
142 | ||
143 | /* | |
144 | * Find a test file under C_TAP_BUILD or C_TAP_SOURCE, returning the full | |
145 | * path. The returned path should be freed with test_file_path_free(). | |
146 | */ | |
147 | char *test_file_path(const char *file) | |
148 | __attribute__((__malloc__, __nonnull__, __warn_unused_result__)); | |
149 | void test_file_path_free(char *path); | |
150 | ||
151 | /* | |
152 | * Create a temporary directory relative to C_TAP_BUILD and return the path. | |
153 | * The returned path should be freed with test_tmpdir_free(). | |
154 | */ | |
155 | char *test_tmpdir(void) | |
156 | __attribute__((__malloc__, __warn_unused_result__)); | |
157 | void test_tmpdir_free(char *path); | |
158 | ||
159 | /* | |
160 | * Register a cleanup function that is called when testing ends. All such | |
161 | * registered functions will be run during atexit handling (and are therefore | |
162 | * subject to all the same constraints and caveats as atexit functions). | |
163 | * | |
164 | * The function must return void and will be passed two arguments: an int that | |
165 | * will be true if the test completed successfully and false otherwise, and an | |
166 | * int that will be true if the cleanup function is run in the primary process | |
167 | * (the one that called plan or plan_lazy) and false otherwise. | |
168 | */ | |
169 | typedef void (*test_cleanup_func)(int, int); | |
170 | void test_cleanup_register(test_cleanup_func) | |
171 | __attribute__((__nonnull__)); | |
172 | ||
173 | END_DECLS | |
174 | ||
175 | #endif /* TAP_BASIC_H */ |