1 /*
2 * SCCS: @(#)tet_api.h 1.31 (99/11/15)
3 *
4 * UniSoft Ltd., London, England
5 *
6 * (C) Copyright 1996 X/Open Company Limited
7 *
8 * All rights reserved. No part of this source code may be reproduced,
9 * stored in a retrieval system, or transmitted, in any form or by any
10 * means, electronic, mechanical, photocopying, recording or otherwise,
11 * except as stated in the end-user licence agreement, without the prior
12 * permission of the copyright owners.
13 * A copy of the end-user licence agreement is contained in the file
14 * Licence which accompanies this distribution.
15 *
16 * X/Open and the 'X' symbol are trademarks of X/Open Company Limited in
17 * the UK and other countries.
18 */
19
20 /*
21 * Copyright 1990 Open Software Foundation (OSF)
22 * Copyright 1990 Unix International (UI)
23 * Copyright 1990 X/Open Company Limited (X/Open)
24 *
25 * Permission to use, copy, modify, and distribute this software and its
26 * documentation for any purpose and without fee is hereby granted, provided
27 * that the above copyright notice appear in all copies and that both that
28 * copyright notice and this permission notice appear in supporting
29 * documentation, and that the name of OSF, UI or X/Open not be used in
30 * advertising or publicity pertaining to distribution of the software
31 * without specific, written prior permission. OSF, UI and X/Open make
32 * no representations about the suitability of this software for any purpose.
33 * It is provided "as is" without express or implied warranty.
34 *
35 * OSF, UI and X/Open DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
36 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
37 * EVENT SHALL OSF, UI or X/Open BE LIABLE FOR ANY SPECIAL, INDIRECT OR
38 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
39 * USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
40 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
41 * PERFORMANCE OF THIS SOFTWARE.
42 */
43
44 /************************************************************************
45
46 SCCS: @(#)tet_api.h 1.31 99/11/15 TETware release 3.7
47 NAME: 'C' API header
48 PRODUCT: TETware
49 AUTHOR: Geoff Clare, UniSoft Ltd.
50 DATE CREATED: 23 July 1990
51 CONTENTS:
52
53 struct tet_testlist definition
54 result code values for use with tet_result()
55 TET_NULLFP null function pointer for use with tet_fork()
56 declarations/prototypes for all API interfaces
57
58 MODIFICATIONS:
59
60 Geoff Clare, UniSoft Ltd., 10 Oct 1990
61 Remove const keywords.
62
63 Geoff Clare, UniSoft Ltd., 18 Oct 1990
64 Add tet_pname.
65
66 Geoff Clare, UniSoft Ltd., 28 Nov 1990
67 Add tet_nosigreset.
68
69 Geoff Clare, UniSoft Ltd., 21 June 1991
70 Make tet_fork() prototype consistent with definition.
71
72 DTET development - this file is derived from TET Release 1.10
73 David G. Sawyer
74 John-Paul Leyland
75 UniSoft Ltd, June 1992
76
77 Andrew Dingwall, UniSoft Ltd., October 1992
78 Added DTET API function declarations.
79
80 Denis McConalogue, UniSoft Limited, September 1993
81 changed prototype for tet_sync()
82
83 Andrew Dingwall, UniSoft Ltd., February 1994
84 removed comment from #include line (for strict ANSI compliance?)
85
86 Andrew Dingwall, UniSoft Ltd., October 1994
87 added support for tet_msync() API function
88
89 Geoff Clare, UniSoft Ltd., July 1996
90 Changes for TETWare.
91
92 Geoff Clare, UniSoft Ltd., Sept 1996
93 Changes for TETWare-Lite and POSIX threads.
94
95 Andrew Dingwall, UniSoft Ltd., June 1997
96 changes to support the defined test case interface
97
98 Geoff Clare, UniSoft Ltd., June 1997
99 Changes for NT threads.
100
101 Andrew Dingwall, UniSoft Ltd., December 1997
102 protect against multiple inclusion
103
104 Andrew Dingwall, UniSoft Ltd., August 1998
105 Added support for shared libraries.
106
107 Andrew Dingwall, UniSoft Ltd., August 1999
108 Added sypport for other language APIs.
109
110 Geoff Clare, UniSoft Ltd., October 1999
111 Added declarations of tet_thr_join(), tet_pthread_join() and
112 tet_pthread_detach().
113
114 Andrew Dingwall, UniSoft Ltd., November 1999
115 added #defines to support strict/unrestricted POSIX threads
116
117 ************************************************************************/
118
119 #ifndef TET_API_H_INCLUDED
120 #define TET_API_H_INCLUDED
121
122 #ifdef __cplusplus
123 extern "C" {
124 #endif
125
126
127 /*
128 ** support for shared API libraries on Win32 systems
129 */
130
131
132 /* not using a shared API library on a Win32 system */
133 # ifndef TET_IMPORT
134 # define TET_IMPORT
135 # endif
136
137
138 #ifndef TET_EXPORT
139 # define TET_EXPORT
140 #endif
141
142 /*
143 ** TET_EXPORT_DATA is used to declare a data item that is exported from
144 ** a program to a shared library.
145 ** TET_IMPORT_DATA, TET_IMPORT_ARRAY, TET_IMPORT_FUNC and TET_IMPORT_FUNC_PTR
146 ** are used to declare a data item, array, function or function pointer that
147 ** is imported by a program from a shared library.
148 ** Definitions used when compiling TETware source files appear in dtmac.h.
149 ** These definitions are sufficient for user-level code.
150 */
151 #ifndef TET_EXPORT_DATA
152 # define TET_EXPORT_DATA(TYPE, NAME) \
153 TET_EXPORT extern TYPE NAME
154 #endif
155 #ifndef TET_IMPORT_DATA
156 # define TET_IMPORT_DATA(TYPE, NAME) \
157 TET_IMPORT extern TYPE NAME
158 #endif
159 #ifndef TET_IMPORT_ARRAY
160 # define TET_IMPORT_ARRAY(TYPE, NAME, DIM) \
161 TET_IMPORT extern TYPE NAME DIM
162 #endif
163 #ifndef TET_IMPORT_FUNC
164 # define TET_IMPORT_FUNC(TYPE, NAME, ARGS) \
165 TET_IMPORT extern TYPE NAME ARGS
166 #endif
167 #ifndef TET_IMPORT_FUNC_PTR
168 # define TET_IMPORT_FUNC_PTR(TYPE, NAME, ARGS) \
169 TET_IMPORT extern TYPE (*NAME) ARGS
170 #endif
171
172 /*
173 ** Support for strict/unrestricted POSIX threads.
174 **
175 ** Users should only define TET_THREADS or TET_POSIX_THREADS.
176 ** TET_UNRESTRICTED_POSIX_THREADS implies TET_POSIX_THREADS, so we define
177 ** TET_POSIX_THREADS here in case some user code has been compiled with
178 ** TET_UNRESTRICTED_POSIX_THREADS defined instead.
179 */
180 #if defined(TET_UNRESTRICTED_POSIX_THREADS) && !defined(TET_POSIX_THREADS)
181 # define TET_POSIX_THREADS 1
182 #endif
183
184 /* the following are needed for types used in declarations */
185 #include <sys/types.h>
186 #define TET_PID_T_DEFINED
187 #if defined(__STDC__) || defined(__cplusplus) || defined(_WIN32)
188 # include <time.h>
189 # include <stdarg.h>
190 #endif
191 #ifdef TET_POSIX_THREADS
192 # include <pthread.h>
193 #else /* !TET_POSIX_THREADS */
194 # ifdef TET_THREADS
195 # ifndef _WIN32
196 # include <thread.h>
197 # endif
198 # endif /* TET_THREADS */
199 #endif /* !TET_POSIX_THREADS */
200
201
202 /* values of the standard result codes - may be passed to tet_result() */
203 #define TET_PASS 0
204 #define TET_FAIL 1
205 #define TET_UNRESOLVED 2
206 #define TET_NOTINUSE 3
207 #define TET_UNSUPPORTED 4
208 #define TET_UNTESTED 5
209 #define TET_UNINITIATED 6
210 #define TET_NORESULT 7
211
212
213 /* tet_errno values, may be used to index into tet_errlist[] */
214 #define TET_ER_OK 0 /* ok success */
215 #define TET_ER_ERR 1 /* general error code */
216 #define TET_ER_MAGIC 2 /* bad magic number */
217 #define TET_ER_LOGON 3 /* not logged on */
218 #define TET_ER_RCVERR 4 /* receive message error */
219 #define TET_ER_REQ 5 /* unknown request code */
220 #define TET_ER_TIMEDOUT 6 /* request timed out */
221 #define TET_ER_DUPS 7 /* request contained duplicate IDs */
222 #define TET_ER_SYNCERR 8 /* sync completed unsuccessfully */
223 #define TET_ER_INVAL 9 /* invalid request parameter */
224 #define TET_ER_TRACE 10 /* tracing not configured */
225 #define TET_ER_WAIT 11 /* process not terminated */
226 #define TET_ER_XRID 12 /* bad xrid in xresd request */
227 #define TET_ER_SNID 13 /* bad snid in syncd request */
228 #define TET_ER_SYSID 14 /* sysid not in system name list */
229 #define TET_ER_INPROGRESS 15 /* event in progress */
230 #define TET_ER_DONE 16 /* event finished or already happened */
231 #define TET_ER_CONTEXT 17 /* request out of context */
232 #define TET_ER_PERM 18 /* priv request/kill error */
233 #define TET_ER_FORK 19 /* can't fork */
234 #define TET_ER_NOENT 20 /* no such file or directory */
235 #define TET_ER_PID 21 /* no such process */
236 #define TET_ER_SIGNUM 22 /* bad signal number */
237 #define TET_ER_FID 23 /* bad file id */
238 #define TET_ER_INTERN 24 /* server internal error */
239 #define TET_ER_ABORT 25 /* abort TCM on TP end */
240 #define TET_ER_2BIG 26 /* argument list too long */
241
242
243 /*
244 ** function prototype macros
245 */
246
247 #if defined(__STDC__) || defined(__cplusplus) || defined(_WIN32)
248 # ifndef TET_PROTOTYPES
249 # define TET_PROTOTYPES
250 # endif
251 #endif
252
253 #ifdef TET_PROTOTYPES
254 # define TET_PROTOLIST(list) list
255 #else
256 # define TET_PROTOLIST(list) ()
257 #endif
258
259
260 /* NULL function pointer - may be used as an argument to tet_fork() */
261 #define TET_NULLFP ((void (*) ()) 0)
262
263
264 #ifndef TET_LITE /* -START-LITE-CUT- */
265
266 /*
267 ** sync requests and sync error reporting
268 */
269
270 /* structure used in tet_msync() and tet_remsync() calls */
271 struct tet_synmsg {
272 char *tsm_data; /* ptr to sync message data buffer */
273 int tsm_dlen; /* no of bytes in sm_data */
274 int tsm_sysid; /* id of system sending sync message data */
275 int tsm_flags; /* flags - see below */
276 };
277
278 /* values for tsm_flags (a bit field) */
279 # define TET_SMSNDMSG 001 /* system is sending message data */
280 # define TET_SMRCVMSG 002 /* system is receiving message data */
281 # define TET_SMDUP 004 /* more than one system attempted to send */
282 # define TET_SMTRUNC 010 /* message data was truncated */
283
284 # define TET_SMMSGMAX 1024 /* maximum size of a tet_msync message -
285 size must be expressable in 12 bits
286 (see ST_COUNTMASK in ldst.h) */
287
288 /* sync votes */
289 # define TET_SV_YES 1
290 # define TET_SV_NO 2
291
292 /* structure of an element in the array describing sync status
293 that is passed by the API to the sync error reporting function */
294 struct tet_syncstat {
295 int tsy_sysid; /* system ID */
296 int tsy_state; /* sync state */
297 };
298
299 /* values for tsy_state */
300 # define TET_SS_NOTSYNCED 1 /* sync request not received */
301 # define TET_SS_SYNCYES 2 /* system voted YES */
302 # define TET_SS_SYNCNO 3 /* system voted NO */
303 # define TET_SS_TIMEDOUT 4 /* system timed out */
304 # define TET_SS_DEAD 5 /* process exited */
305
306
307 /* structure of the data item that is filled in by tet_getsysbyid() */
308 # define TET_SNAMELEN 32 /* maximum system name length */
309 struct tet_sysent {
310 int ts_sysid; /* system ID */
311 char ts_name[TET_SNAMELEN]; /* system name */
312 };
313
314 #endif /* -END-LITE-CUT- */
315
316
317 /*
318 ** declarations of public functions provided by the API
319 */
320
321 /* functions in TETware-Lite and in Distrubuted TETware */
322 TET_IMPORT_FUNC(void, tet_delete, TET_PROTOLIST((int, char *)));
323 TET_IMPORT_FUNC(void, tet_exit, TET_PROTOLIST((int)));
324 TET_IMPORT_FUNC(char *, tet_getvar, TET_PROTOLIST((char *)));
325 TET_IMPORT_FUNC(void, tet_infoline, TET_PROTOLIST((char *)));
326 TET_IMPORT_FUNC(int, tet_kill, TET_PROTOLIST((pid_t, int)));
327 TET_IMPORT_FUNC(void, tet_logoff, TET_PROTOLIST((void)));
328 TET_IMPORT_FUNC(int, tet_minfoline, TET_PROTOLIST((char **, int)));
329 TET_IMPORT_FUNC(int, tet_printf, TET_PROTOLIST((char *, ...)));
330 TET_IMPORT_FUNC(char *, tet_reason, TET_PROTOLIST((int)));
331 TET_IMPORT_FUNC(int, tet_remgetlist, TET_PROTOLIST((int **)));
332 TET_IMPORT_FUNC(int, tet_remgetsys, TET_PROTOLIST((void)));
333 TET_IMPORT_FUNC(void, tet_result, TET_PROTOLIST((int)));
334 TET_IMPORT_FUNC(void, tet_setblock, TET_PROTOLIST((void)));
335 TET_IMPORT_FUNC(void, tet_setcontext, TET_PROTOLIST((void)));
336 TET_IMPORT_FUNC(pid_t, tet_spawn, TET_PROTOLIST((char *, char **, char **)));
337 TET_IMPORT_FUNC(int, tet_vprintf, TET_PROTOLIST((char *, va_list)));
338 TET_IMPORT_FUNC(int, tet_wait, TET_PROTOLIST((pid_t, int *)));
339 #ifndef _WIN32
340 TET_IMPORT_FUNC(int, tet_exec, TET_PROTOLIST((char *, char *[], char *[])));
341 TET_IMPORT_FUNC(int, tet_fork,
342 TET_PROTOLIST((void (*) TET_PROTOLIST((void)),
343 void (*) TET_PROTOLIST((void)), int, int)));
344 #endif /* !_WIN32 */
345
346 /* functions only in Distributed TETware */
347 #ifndef TET_LITE /* -START-LITE-CUT- */
348 TET_IMPORT_FUNC(int, tet_getsysbyid,
349 TET_PROTOLIST((int, struct tet_sysent *)));
350 TET_IMPORT_FUNC(int, tet_msync,
351 TET_PROTOLIST((long, int *, int, struct tet_synmsg *)));
352 TET_IMPORT_FUNC(int, tet_remsync,
353 TET_PROTOLIST((long, int *, int, int, int, struct tet_synmsg *)));
354 TET_IMPORT_FUNC(int, tet_remtime, TET_PROTOLIST((int, time_t *)));
355 TET_IMPORT_FUNC(int, tet_sync, TET_PROTOLIST((long, int *, int)));
356 TET_IMPORT_FUNC(void, tet_syncreport,
357 TET_PROTOLIST((long, struct tet_syncstat *, int)));
358 # if !defined(TET_THREADS) && !defined(TET_POSIX_THREADS)
359 TET_IMPORT_FUNC(int, tet_remexec, TET_PROTOLIST((int, char *, char **)));
360 TET_IMPORT_FUNC(int, tet_remkill, TET_PROTOLIST((int)));
361 TET_IMPORT_FUNC(int, tet_remwait, TET_PROTOLIST((int, int, int *)));
362 # endif /* !THREADS */
363 #endif /* -END-LITE-CUT- */
364
365 /* functions only in the Thread-safe API */
366 #if defined(TET_THREADS) || defined(TET_POSIX_THREADS)
367 # ifdef TET_POSIX_THREADS
368 TET_IMPORT_FUNC(int, tet_pthread_create,
369 TET_PROTOLIST((pthread_t *, pthread_attr_t *,
370 void *(*) TET_PROTOLIST((void *)), void *, int)));
371 TET_IMPORT_FUNC(int, tet_pthread_join, TET_PROTOLIST((pthread_t, void **)));
372 TET_IMPORT_FUNC(int, tet_pthread_detach, TET_PROTOLIST((pthread_t)));
373 # else /* !TET_POSIX_THREADS */
374 TET_IMPORT_FUNC(int, tet_thr_create,
375 TET_PROTOLIST((void *, size_t, void *(*) TET_PROTOLIST((void *)),
376 void *, long, thread_t *, int)));
377 TET_IMPORT_FUNC(int, tet_thr_join, TET_PROTOLIST((thread_t, void **)));
378 # endif /* !TET_POSIX_THREADS */
379 # ifndef _WIN32
380 TET_IMPORT_FUNC(int, tet_fork1,
381 TET_PROTOLIST((void (*) TET_PROTOLIST((void)),
382 void (*) TET_PROTOLIST((void)), int, int)));
383 # endif /* !_WIN32 */
384 #endif /* THREADS */
385
386
387 /*
388 ** declarations of public data items provided by the API
389 */
390
391 /* the following are imported from the API library */
392 #if defined(TET_THREADS) || defined(TET_POSIX_THREADS)
393 # ifndef _WIN32
394 # define tet_child (*tet_thr_child())
395 TET_IMPORT_FUNC(pid_t *, tet_thr_child, TET_PROTOLIST((void)));
396 # endif /* !_WIN32 */
397 # define tet_errno (*tet_thr_errno())
398 TET_IMPORT_FUNC(int *, tet_thr_errno, TET_PROTOLIST((void)));
399 #else /* !THREADS */
400 # ifndef _WIN32
401 TET_IMPORT_DATA(pid_t, tet_child);
402 # endif /* !_WIN32 */
403 TET_IMPORT_DATA(int, tet_errno);
404 #endif /* !THREADS */
405
406 TET_IMPORT_ARRAY(char *, tet_errlist, []);
407 TET_IMPORT_DATA(int, tet_nerr);
408 #ifndef TET_LITE /* -START-LITE-CUT- */
409 TET_IMPORT_FUNC_PTR(void, tet_syncerr,
410 TET_PROTOLIST((long, struct tet_syncstat *, int)));
411 #endif /* -END-LITE-CUT- */
412
413 /* the following are in the TCM */
414 extern int tet_nosigreset;
415
416 /* the following are in the TCM and must be "exported" to the API library */
417 TET_IMPORT_DATA(char *, tet_pname);
418 TET_IMPORT_DATA(int, tet_thistest);
419
420
421 /*
422 ** declarations used by the interface between the TCM and the test case
423 **
424 ** these items must be provided by the user
425 */
426
427 /* the test case startup and cleanup functions */
428 extern void (*tet_startup)();
429 extern void (*tet_cleanup)();
430
431 /* and EITHER this data structure */
432 struct tet_testlist {
433 void (*testfunc)();
434 int icref;
435 };
436 extern struct tet_testlist tet_testlist[];
437
438 /* OR all of these test case interface functions */
439 extern int tet_getmaxic TET_PROTOLIST((void));
440 extern int tet_getminic TET_PROTOLIST((void));
441 extern int tet_gettestnum TET_PROTOLIST((int, int));
442 extern int tet_gettpcount TET_PROTOLIST((int));
443 extern int tet_invoketp TET_PROTOLIST((int, int));
444 extern int tet_isdefic TET_PROTOLIST((int));
445
446
447 /*
448 ** declaration of the interface between an executed program and the
449 ** child process controller
450 **
451 ** this item must be provided by the user
452 */
453
454 extern int tet_main TET_PROTOLIST((int, char *[]));
455
456
457 /*
458 ** declarations of other public interfaces provided by the API
459 **
460 ** these interfaces should not be used by C/C++ test cases but are
461 ** provided to support other language APIs that use the C API
462 */
463
464 /* the entry points into the TCM and the child process controllers */
465 extern void tet_tcm_main TET_PROTOLIST((int, char **));
466 extern void tet_tcmchild_main TET_PROTOLIST((int, char **));
467 #ifndef TET_LITE /* -START-LITE-CUT- */
468 extern void tet_tcmrem_main TET_PROTOLIST((int, char **));
469 #endif /* -END-LITE-CUT- */
470
471 /* the block and sequence numbers used when the API writes to the journal */
472 #if defined(TET_THREADS) || defined(TET_POSIX_THREADS)
473 TET_IMPORT_FUNC(long *, tet_thr_block, TET_PROTOLIST((void)));
474 # define tet_block (*tet_thr_block())
475 TET_IMPORT_FUNC(long *, tet_thr_sequence, TET_PROTOLIST((void)));
476 # define tet_sequence (*tet_thr_sequence())
477 TET_IMPORT_DATA(long, tet_next_block);
478 #else
479 TET_IMPORT_DATA(long, tet_block);
480 TET_IMPORT_DATA(long, tet_sequence);
481 #endif
482
483 /* the TCM/API error reporting functions */
484 TET_IMPORT_FUNC(void, tet_merror, TET_PROTOLIST((int, char **, int)));
485 TET_IMPORT_FUNC(void, tet_error, TET_PROTOLIST((int, char *)));
486
487
488 #ifdef __cplusplus
489 }
490 #endif
491
492 #endif /* TET_API_H_INCLUDED */
493