1 /************************************************************************
3 * driver.h - testsuite driver declarations
5 * $Id: driver.h 287304 2005-09-15 00:41:16Z sebor $
7 ***************************************************************************
9 * Copyright (c) 1994-2005 Quovadx, Inc., acting through its Rogue Wave
10 * Software division. Licensed under the Apache License, Version 2.0 (the
11 * "License"); you may not use this file except in compliance with the
12 * License. You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0. Unless required by
14 * applicable law or agreed to in writing, software distributed under
15 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
16 * CONDITIONS OF ANY KIND, either express or implied. See the License
17 * for the specific language governing permissions and limitations under
20 **************************************************************************/
22 #ifndef RW_DRIVER_H_INCLUDED
23 #define RW_DRIVER_H_INCLUDED
25 #include <testdefs.h> // for test config macros
29 * Initializes the test driver, passes program arguments to it, processes
30 * command line arguments, any arguments specified in the environment
31 * variable RWSTD_TESTOPTS, and if successful, invokes the program-supplied
34 * @param argc The number of non-null elements in the argv array.
35 * @param argv A null-terminated array of command line arguments.
36 * If (argc == 0) the argument may be null.
37 * @param filename The name of the source file name, typically
38 * the __FILE__ macro. The argument may be null.
39 * @param clause The clause exercised by the program, such as
40 * lib.basic.string. The argument may be null.
41 * @param comment An optional comment describing in more detail
42 * the functionality of the program. The argument may be null.
43 * @param testfun A pointer to a callback function to call by the
44 * driver after successful initialization. The argument must
46 * @param optspec An optional character string describing command
47 * line options accepted by the program. The argument may
49 * @param ... Optional list of handlers of command line options
50 * corresponding to the optspec.
52 * @return If initialization is successful, returns the value returned
53 * by the callback function. Otherwise, returns the non-zero
54 * value returned by the last initialization function or
55 * command line option handler.
57 * After the driver has been initialzied the user-supplied callback function
58 * may call any of the driver diagnostic functions to record and perhaps also
59 * issue diagnostic messages of varying severity.
61 * There are 10 levels of severity with 0 being the lowest and 9 the highest.
62 * Diagnostics of all levels of severity come in two states: active and
63 * inactive. All diagnostics are recorded but normally only active diagnostics
64 * of severity 4 or above are issued. It is possible to cause diagnostics of
65 * lower severity levels to be issued via a command line option to the driver.
66 * Choosing to issue severity 0 diagnostics has the effect of issuing inactive
69 * After the callback function returns the driver displays a summary detailing
70 * the number of recorded diagnostics in each of the two states (active and
80 int (*testfun)(int, char**),
85 * Records and optionally issues a diagnostic of the highest severity 9.
87 * @param expr A zero value denoting an active diagnostic or any non-zero
88 * vaue denoting an inactive diagnostic.
89 * @param filename An optional name of the file invoking the function.
90 * The argument may be null.
91 * @param line When positive, denotes the line number of the location
92 * relevant to the diagnostic. Negative values are ignored.
93 * @param fmtspec A printf format specifier (with extensions) used
94 * to format the text of the diagnostic.
95 * @param ... Optional list of values to format.
97 * @return Returns the value of expr passed to it.
99 * Every diagnostic is recorded but only active diagnostics may be issued,
100 * depending on the setting of the diagnosable severity. The value of the
101 * first argument determines whether a diagnostc is active or inactive.
102 * Unlike the remaining diagnostic functions, rw_fatal doesn't return to
103 * the caller when expr is 0 (i.e., when the diagnostic is active).
104 * Instead, it causes the driver the exit the process with the staus equal
105 * to 9, the severity of the diagnostic.
109 const char* filename,
115 * Records and optionally issues a diagnostic of severity 8.
120 rw_error (int, const char*, int, const char*, ...);
123 * Records and optionally issues a diagnostic of severity 7.
128 rw_assert (int, const char*, int, const char*, ...);
131 * Records and optionally issues a diagnostic of severity 5.
136 rw_warn (int, const char*, int, const char*, ...);
139 * Records and optionally issues a diagnostic of severity 2.
144 rw_note (int, const char*, int, const char*, ...);
147 * Records and optionally issues a diagnostic of severity 1.
152 rw_info (int, const char*, int, const char*, ...);
154 #endif // RW_DRIVER_H_INCLUDED