src/common/dmessage.h

/* RCSid $Id$ */
/*
 *  dmessage.h
 *  panlib
 *
 *  Depends on <stdio.h>
 *
 *  Debug and error message logging and recovery.
 *
 *  Created by gward on Thu May 10 2001.
 *  Modified by plonghurst on Thursday Feb 15 2007.
 *  Copyright (c) 2001 Anyhere Software. All rights reserved.
 *
 */

#ifndef _DMESSAGE_H_
#define _DMESSAGE_H_

#ifdef __cplusplus
extern "C" {
#endif

/********************
 * Type Definitions *
 ********************/

/***********************************************************************
 * Debug message classes
 *
 *  If you are unsure what class to report, guess on the high side, which
 *  is less serious.  For example, report an error like DMCdata even
 *  when you think it's DMCsystem, unless you really know.
 *  That way, more serious errors will be recorded from higher in the call
 *  tree.  The vast majority of errors fall into the DMCdata class.
 */
typedef enum {
                DMCassert,              /* assertion failure */
                DMCmemory,              /* out of memory */
                DMCsystem,              /* system error */
                DMCparameter,           /* program parameter error */
                DMCresource,            /* file/resource unavailable */
                DMCdata,                /* data error */
                DMCinput,               /* input error */
                DMCwarning,             /* warning message */
                DMCinfo,                /* informative output */
                DMCtrace,               /* trace point */
                DMCnerr                 /* no error (terminator) */
} DMsgClass;

/***********************************************************************
 * Message flags:  record, write to logfile, send to stderr,
 *                      alert user, exit program, abort
 */
typedef enum {
                DMFrecord=01, DMFlog=02, DMFstderr=04,
                DMFalert=010, DMFexit=020, DMFabort=040
} DMsgFlag;

/************************
 * Functions and Macros *
 ************************/

/***********************************************************************
 * int
 * dmessage(int cls, const char *msg, const char *file, int line);
 *
 *  Basic call interface to debug message handler.  The file name
 *  and line number are generally taken from the ANSI-C __FILE__
 *  and __LINE__ predefined macros.  The message class are taken
 *  from the list above, and the message should not contain newlines.
 *  All DMsgClass classes except DMCassert are recoverable and
 *  dmessage() will return.  The return value is an or'ing of
 *  DMsgFlags according to what was done.
 */
#ifdef __cplusplus
extern int      dmessage(DMsgClass cls, const char *msg,
                        const char *file = NULL, int line = 0);
#else
extern int      dmessage(DMsgClass cls, const char *msg,
                        const char *file, int line);
#endif

/***********************************************************************
 * int
 * DMESG(int cls, const char *msg)
 *
 *  Basic macro call for message reporting.  What actually happens to
 *  the message depends on the current settings, controlled by
 *  global variables described in the next section.
 */
#define DMESG(cls, msg)         dmessage(cls, msg, __FILE__, __LINE__)

/***********************************************************************
 * int
 * DTEST(int cnd, int cls, const char *msg)
 *
 *  Conditional call to DMESG() for convenience.  Zero is returned if
 *  the condition (cnd) evaluates to zero, and a collection of DMsgFlags
 *  saying what was done if the condition evaluates to non-zero.
 */
#define DTEST(cnd, cls, msg)    ((cnd) ? DMESG(cls, msg) : 0)

/***********************************************************************
 * int
 * DMESGF(int cls, const char *fmt, va_list..)
 *
 *  Formatting version of DMESG() takes printf(3) format string
 *  and a variable argument list to format the message.
 */
#define DMESGF(cls, fmt, val)   (sprintf(dmessage_buf, fmt, val), \
                                        DMESG(cls, dmessage_buf))

/***********************************************************************
 * int
 * DTESTF(int cnd, DMsgClass cls, const char *fmt, va_list..)
 *
 *  Formatting version of DTEST() takes printf(3) format string
 *  and a variable argument list to format the message, but only
 *  if the condition (cnd) evaluates to non-zero.
 */
#define DTESTF(cnd, cls, fmt, val) \
                                ((cnd) ? DMESGF(cls, fmt, val) : 0)

/***********************************************************************
 * int
 * DRESET()
 *
 *  Reset last error message class.  Call before potential error-
 *  producing subroutine, then call DMESC() or DMESCF() afterwards.
 */
#define DRESET()        (dmessage_last_class = DMCnerr)

/***********************************************************************
 * int
 * DMESC(int cls, const char *msg)
 *
 *  Report only if this error is a higher priority than any since
 *  DRESET() was last called.
 */
#define DMESC(cls, msg)         DTEST((cls) < dmessage_last_class, \
                                        cls, msg)
 
/***********************************************************************
 * int
 * DMESCF(int cls, const char *fmt, va_list..)
 *
 *  Formatting version of DMESC() takes printf(3) format string, but
 *  only reports if this error is higher priority than any since
 *  DRESET() was last called.
 */
#define DMESCF(cls, fmt, val)   DTESTF((cls) < dmessage_last_class, \
                                        cls, fmt, val)

/***********************************************************************
 * void
 * DASSERT(int cnd)
 *
 *  Replacement for assert() macro; calls DTEST() with DMCassert class
 *  if asc yeilds 0.  If NDEBUG is defined, the macro becomes a no-op.
 */
#ifdef NDEBUG
#define DASSERT(asc)            ((void)0)
#else
#if defined(__STDC__) || defined(__cplusplus)
#define DASSERT(asc)            ((void)DTESTF(!(asc), DMCassert, \
                                        "assertion failed ! (%s)", #asc))
#else
#define DASSERT(asc)            ((void)DTESTF(!(asc), DMCassert, \
                                        "assertion failed ! (%s)", "asc"))
#endif
#endif

/*********************
 * Global Variabless *
 *********************/

/***********************************************************************
 * char                 dmessage_buf[DM_BUF_LEN]
 *
 *  Buffer to hold formatted message contents temporarily.
 */
#define DM_BUF_LEN      1024

extern char             dmessage_buf[DM_BUF_LEN];

/***********************************************************************
 * const char *         dmessage_class_name[]
 *
 *  The name of each of class in DMsgClass.
 */
extern const char *     dmessage_class_name[];

/***********************************************************************
 * int                  dmessage_class_flags[]
 *
 *  Flags indicating what to do with each message class.  By default,
 *  the most recent message will be stored in the dmessage_last[] array
 *  (DMFrecord), but if other flags are set, the message will be sent
 *  other places as well.  These flags are available to be altered by the
 *  controlling application, and will not be changed from their initial
 *  defaults (DMFrecord at minimum) by any of the dmessage routines.
 *  Beware:  if the DMrecord flag is turned off for a given class and
 *  dmessage() fails to do anything, it will return zero and
 *  the DTEST() and DTESTF() macro calls may return zero even
 *  though their condition evaluated to non-zero.  This problem is
 *  avoided by keeping DMrecord set for all classes.
 */
extern int              dmessage_class_flags[];

/***********************************************************************
 * int                  dmessage_class_done[]
 *
 *  Flags indicating what was last done with each message class.
 *  In other words, the last result of dmessage() for each class.
 */
extern int              dmessage_class_done[];

/***********************************************************************
 * const char *         dmessage_file[]
 *
 *  Most recent file reported for each error class.
 */
extern const char *     dmessage_file[];

/***********************************************************************
 * int                  dmessage_line[]
 *
 *  Most recent line number reported for each error class.
 */
extern int              dmessage_line[];

/***********************************************************************
 * const char *         dmessage_record[]
 *
 *  Most recent message for each class with the DMFrecord flag set,
 *  exactly as passed to dmessage().  If no message of
 *  a given class has been reported, then the corresponding
 *  dmessage_record pointer will be NULL.
 */
extern const char *     dmessage_record[];

/***********************************************************************
 * int                  dmessage_last_class
 *
 *  The lowest class message reported so far, set to DMCnerr initially.
 *  The DMESG_LAST macro provides convenient access to most recent error.
 */
extern DMsgClass        dmessage_last_class;

#define DMESG_LAST      (dmessage_record[dmessage_last_class])

/***********************************************************************
 * FILE *               dmessage_logfp
 *
 *  Pointer to open log file.  Each message is preceeded by the file
 *  name, line number, and class for log file and stderr output.  Data
 *  is flushed after each message.  If this pointer is NULL (the default),
 *  then logging is disabled even for classes with the DMFlog flag set.
 */
extern FILE *           dmessage_logfp;

/***********************************************************************
 * int                  (*dmessage_call)(DMsgClass cls, const char *msg,
 *                                      const char *file, int line)
 *
 *  Pointer to function called by dmessage() to share error handling.
 *  If assigned, this function is called with the same arguments passed
 *  to dmessage(), independent of the class flag settings.  The returned
 *  value is then used as a mask on the class flags to turn off some or
 *  all of the default actions.  The flagged actions are considered
 *  "done" and set accordingly in the dmessage_class_done global.
 *  Defaults to NULL.
 */
extern int              (*dmessage_call)(DMsgClass cls, const char *msg,
                                        const char *file, int line);

/***********************************************************************
 * int                  (*dmessage_alert)(const char *msg)
 *
 *  Pointer to function called by dmessage() to alert user.
 *  The function should return non-zero if the user was notified,
 *  or zero if the message could not be displayed for some reason.
 *  Defaults to NULL, which results in no DMFalert action.
 */
extern int              (*dmessage_alert)(const char *msg);

/***********************************************************************
 * void                 (*dmessage_exit)(int status)
 *
 *  Pointer to function called by dmessage() for classes with the
 *  DMFexit flag set, which is usually reserved for the DMCmemory class.
 *  Defaults to system exit() function, but may be reassigned by the
 *  controlling application.  Assigning a value of NULL causes dmessage()
 *  to return from these calls, which might result in a memory fault if
 *  your program does not check for NULL pointer values.  In general,
 *  library authors should NOT assume the DMCmemory class calls exit().
 */
extern void             (*dmessage_exit)(int status);

/***********************************************************************
 * void                 (*dmessage_abort)()
 *
 *  Pointer to function called by dmessage() for classes with the
 *  DMFabort flag set, which is usually reserved for the DMCassert class.
 *  Defaults to system abort() function, but may be reassigned by the
 *  controlling application.  Assigning a value of NULL causes dmessage()
 *  to return from these calls, which will probably prove disasterous.
 *  A better idea if the program wants to continue is to use setjmp() and
 *  longjmp() to recover control at a lower point in the call tree.  If
 *  assigned, this call should never return.
 */
extern void             (*dmessage_abort)();

#ifdef __cplusplus
}
#endif

#endif /* ! _DMESSAGE_H_ */
Revision:	2.2
Committed:	Sun Jun 1 03:25:17 2025 UTC (4 days, 14 hours ago) by greg
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Changes since 2.1:	+1 -0 lines
Log Message:	chore: Added missing RCSid line
#	Content
1	/* RCSid $Id$ */
2	/*
3	* dmessage.h
4	* panlib
5	*
6	* Depends on <stdio.h>
7	*
8	* Debug and error message logging and recovery.
9	*
10	* Created by gward on Thu May 10 2001.
11	* Modified by plonghurst on Thursday Feb 15 2007.
12	* Copyright (c) 2001 Anyhere Software. All rights reserved.
13	*
14	*/
15
16	#ifndef _DMESSAGE_H_
17	#define _DMESSAGE_H_
18
19	#ifdef __cplusplus
20	extern "C" {
21	#endif
22
23	/********************
24	* Type Definitions *
25	********************/
26
27	/***********************************************************************
28	* Debug message classes
29	*
30	* If you are unsure what class to report, guess on the high side, which
31	* is less serious. For example, report an error like DMCdata even
32	* when you think it's DMCsystem, unless you really know.
33	* That way, more serious errors will be recorded from higher in the call
34	* tree. The vast majority of errors fall into the DMCdata class.
35	*/
36	typedef enum {
37	DMCassert, /* assertion failure */
38	DMCmemory, /* out of memory */
39	DMCsystem, /* system error */
40	DMCparameter, /* program parameter error */
41	DMCresource, /* file/resource unavailable */
42	DMCdata, /* data error */
43	DMCinput, /* input error */
44	DMCwarning, /* warning message */
45	DMCinfo, /* informative output */
46	DMCtrace, /* trace point */
47	DMCnerr /* no error (terminator) */
48	} DMsgClass;
49
50	/***********************************************************************
51	* Message flags: record, write to logfile, send to stderr,
52	* alert user, exit program, abort
53	*/
54	typedef enum {
55	DMFrecord=01, DMFlog=02, DMFstderr=04,
56	DMFalert=010, DMFexit=020, DMFabort=040
57	} DMsgFlag;
58
59	/************************
60	* Functions and Macros *
61	************************/
62
63	/***********************************************************************
64	* int
65	* dmessage(int cls, const char msg, const char file, int line);
66	*
67	* Basic call interface to debug message handler. The file name
68	* and line number are generally taken from the ANSI-C __FILE__
69	* and __LINE__ predefined macros. The message class are taken
70	* from the list above, and the message should not contain newlines.
71	* All DMsgClass classes except DMCassert are recoverable and
72	* dmessage() will return. The return value is an or'ing of
73	* DMsgFlags according to what was done.
74	*/
75	#ifdef __cplusplus
76	extern int dmessage(DMsgClass cls, const char *msg,
77	const char *file = NULL, int line = 0);
78	#else
79	extern int dmessage(DMsgClass cls, const char *msg,
80	const char *file, int line);
81	#endif
82
83	/***********************************************************************
84	* int
85	* DMESG(int cls, const char *msg)
86	*
87	* Basic macro call for message reporting. What actually happens to
88	* the message depends on the current settings, controlled by
89	* global variables described in the next section.
90	*/
91	#define DMESG(cls, msg) dmessage(cls, msg, __FILE__, __LINE__)
92
93	/***********************************************************************
94	* int
95	* DTEST(int cnd, int cls, const char *msg)
96	*
97	* Conditional call to DMESG() for convenience. Zero is returned if
98	* the condition (cnd) evaluates to zero, and a collection of DMsgFlags
99	* saying what was done if the condition evaluates to non-zero.
100	*/
101	#define DTEST(cnd, cls, msg) ((cnd) ? DMESG(cls, msg) : 0)
102
103	/***********************************************************************
104	* int
105	* DMESGF(int cls, const char *fmt, va_list..)
106	*
107	* Formatting version of DMESG() takes printf(3) format string
108	* and a variable argument list to format the message.
109	*/
110	#define DMESGF(cls, fmt, val) (sprintf(dmessage_buf, fmt, val), \
111	DMESG(cls, dmessage_buf))
112
113	/***********************************************************************
114	* int
115	* DTESTF(int cnd, DMsgClass cls, const char *fmt, va_list..)
116	*
117	* Formatting version of DTEST() takes printf(3) format string
118	* and a variable argument list to format the message, but only
119	* if the condition (cnd) evaluates to non-zero.
120	*/
121	#define DTESTF(cnd, cls, fmt, val) \
122	((cnd) ? DMESGF(cls, fmt, val) : 0)
123
124	/***********************************************************************
125	* int
126	* DRESET()
127	*
128	* Reset last error message class. Call before potential error-
129	* producing subroutine, then call DMESC() or DMESCF() afterwards.
130	*/
131	#define DRESET() (dmessage_last_class = DMCnerr)
132
133	/***********************************************************************
134	* int
135	* DMESC(int cls, const char *msg)
136	*
137	* Report only if this error is a higher priority than any since
138	* DRESET() was last called.
139	*/
140	#define DMESC(cls, msg) DTEST((cls) < dmessage_last_class, \
141	cls, msg)
142
143	/***********************************************************************
144	* int
145	* DMESCF(int cls, const char *fmt, va_list..)
146	*
147	* Formatting version of DMESC() takes printf(3) format string, but
148	* only reports if this error is higher priority than any since
149	* DRESET() was last called.
150	*/
151	#define DMESCF(cls, fmt, val) DTESTF((cls) < dmessage_last_class, \
152	cls, fmt, val)
153
154	/***********************************************************************
155	* void
156	* DASSERT(int cnd)
157	*
158	* Replacement for assert() macro; calls DTEST() with DMCassert class
159	* if asc yeilds 0. If NDEBUG is defined, the macro becomes a no-op.
160	*/
161	#ifdef NDEBUG
162	#define DASSERT(asc) ((void)0)
163	#else
164	#if defined(__STDC__) \|\| defined(__cplusplus)
165	#define DASSERT(asc) ((void)DTESTF(!(asc), DMCassert, \
166	"assertion failed ! (%s)", #asc))
167	#else
168	#define DASSERT(asc) ((void)DTESTF(!(asc), DMCassert, \
169	"assertion failed ! (%s)", "asc"))
170	#endif
171	#endif
172
173	/*********************
174	* Global Variabless *
175	*********************/
176
177	/***********************************************************************
178	* char dmessage_buf[DM_BUF_LEN]
179	*
180	* Buffer to hold formatted message contents temporarily.
181	*/
182	#define DM_BUF_LEN 1024
183
184	extern char dmessage_buf[DM_BUF_LEN];
185
186	/***********************************************************************
187	* const char * dmessage_class_name[]
188	*
189	* The name of each of class in DMsgClass.
190	*/
191	extern const char * dmessage_class_name[];
192
193	/***********************************************************************
194	* int dmessage_class_flags[]
195	*
196	* Flags indicating what to do with each message class. By default,
197	* the most recent message will be stored in the dmessage_last[] array
198	* (DMFrecord), but if other flags are set, the message will be sent
199	* other places as well. These flags are available to be altered by the
200	* controlling application, and will not be changed from their initial
201	* defaults (DMFrecord at minimum) by any of the dmessage routines.
202	* Beware: if the DMrecord flag is turned off for a given class and
203	* dmessage() fails to do anything, it will return zero and
204	* the DTEST() and DTESTF() macro calls may return zero even
205	* though their condition evaluated to non-zero. This problem is
206	* avoided by keeping DMrecord set for all classes.
207	*/
208	extern int dmessage_class_flags[];
209
210	/***********************************************************************
211	* int dmessage_class_done[]
212	*
213	* Flags indicating what was last done with each message class.
214	* In other words, the last result of dmessage() for each class.
215	*/
216	extern int dmessage_class_done[];
217
218	/***********************************************************************
219	* const char * dmessage_file[]
220	*
221	* Most recent file reported for each error class.
222	*/
223	extern const char * dmessage_file[];
224
225	/***********************************************************************
226	* int dmessage_line[]
227	*
228	* Most recent line number reported for each error class.
229	*/
230	extern int dmessage_line[];
231
232	/***********************************************************************
233	* const char * dmessage_record[]
234	*
235	* Most recent message for each class with the DMFrecord flag set,
236	* exactly as passed to dmessage(). If no message of
237	* a given class has been reported, then the corresponding
238	* dmessage_record pointer will be NULL.
239	*/
240	extern const char * dmessage_record[];
241
242	/***********************************************************************
243	* int dmessage_last_class
244	*
245	* The lowest class message reported so far, set to DMCnerr initially.
246	* The DMESG_LAST macro provides convenient access to most recent error.
247	*/
248	extern DMsgClass dmessage_last_class;
249
250	#define DMESG_LAST (dmessage_record[dmessage_last_class])
251
252	/***********************************************************************
253	* FILE * dmessage_logfp
254	*
255	* Pointer to open log file. Each message is preceeded by the file
256	* name, line number, and class for log file and stderr output. Data
257	* is flushed after each message. If this pointer is NULL (the default),
258	* then logging is disabled even for classes with the DMFlog flag set.
259	*/
260	extern FILE * dmessage_logfp;
261
262	/***********************************************************************
263	* int (dmessage_call)(DMsgClass cls, const char msg,
264	* const char *file, int line)
265	*
266	* Pointer to function called by dmessage() to share error handling.
267	* If assigned, this function is called with the same arguments passed
268	* to dmessage(), independent of the class flag settings. The returned
269	* value is then used as a mask on the class flags to turn off some or
270	* all of the default actions. The flagged actions are considered
271	* "done" and set accordingly in the dmessage_class_done global.
272	* Defaults to NULL.
273	*/
274	extern int (dmessage_call)(DMsgClass cls, const char msg,
275	const char *file, int line);
276
277	/***********************************************************************
278	* int (dmessage_alert)(const char msg)
279	*
280	* Pointer to function called by dmessage() to alert user.
281	* The function should return non-zero if the user was notified,
282	* or zero if the message could not be displayed for some reason.
283	* Defaults to NULL, which results in no DMFalert action.
284	*/
285	extern int (dmessage_alert)(const char msg);
286
287	/***********************************************************************
288	* void (*dmessage_exit)(int status)
289	*
290	* Pointer to function called by dmessage() for classes with the
291	* DMFexit flag set, which is usually reserved for the DMCmemory class.
292	* Defaults to system exit() function, but may be reassigned by the
293	* controlling application. Assigning a value of NULL causes dmessage()
294	* to return from these calls, which might result in a memory fault if
295	* your program does not check for NULL pointer values. In general,
296	* library authors should NOT assume the DMCmemory class calls exit().
297	*/
298	extern void (*dmessage_exit)(int status);
299
300	/***********************************************************************
301	* void (*dmessage_abort)()
302	*
303	* Pointer to function called by dmessage() for classes with the
304	* DMFabort flag set, which is usually reserved for the DMCassert class.
305	* Defaults to system abort() function, but may be reassigned by the
306	* controlling application. Assigning a value of NULL causes dmessage()
307	* to return from these calls, which will probably prove disasterous.
308	* A better idea if the program wants to continue is to use setjmp() and
309	* longjmp() to recover control at a lower point in the call tree. If
310	* assigned, this call should never return.
311	*/
312	extern void (*dmessage_abort)();
313
314	#ifdef __cplusplus
315	}
316	#endif
317
318	#endif /* ! _DMESSAGE_H_ */