Infrastructure: Split the files into subdirectories.

[mLib] / trace / trace.h

diff --git a/trace/trace.h b/trace/trace.h
new file mode 100644 (file)
index 0000000..77e5ed4
--- /dev/null
+++ b/trace/trace.h
@@ -0,0 +1,159 @@
+/* -*-c-*-
+ *
+ * Tracing functions for debugging
+ *
+ * (c) 1998 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of the mLib utilities library.
+ *
+ * mLib is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * mLib is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with mLib; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+#ifndef MLIB_TRACE_H
+#define MLIB_TRACE_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stdio.h>
+
+/*----- Data structures ---------------------------------------------------*/
+
+typedef struct trace_opt {
+  char ch;
+  unsigned f;
+  const char *help;
+} trace_opt;
+
+/*----- Functions provided ------------------------------------------------*/
+
+/* --- @trace@ --- *
+ *
+ * Arguments:  @unsigned l@ = trace level for output
+ *             @const char *f@ = a @printf@-style format string
+ *             @...@ = other arguments
+ *
+ * Returns:    ---
+ *
+ * Use:                Reports a message to the trace output.
+ */
+
+extern void trace(unsigned /*l*/, const char */*f*/, ...);
+
+/* --- @trace_block@ --- *
+ *
+ * Arguments:  @unsigned l@ = trace level for output
+ *             @const char *s@ = some header string to write
+ *             @const void *b@ = pointer to a block of memory to dump
+ *             @size_t sz@ = size of the block of memory
+ *
+ * Returns:    ---
+ *
+ * Use:                Dumps the contents of a block to the trace output.
+ */
+
+extern void trace_block(unsigned /*l*/, const char */*s*/,
+                       const void */*b*/, size_t /*sz*/);
+
+/* --- @trace_on@ --- *
+ *
+ * Arguments:  @FILE *fp@ = a file to trace on
+ *             @unsigned l@ = trace level to set
+ *
+ * Returns:    ---
+ *
+ * Use:                Enables tracing to a file.
+ */
+
+extern void trace_on(FILE */*fp*/, unsigned /*l*/);
+
+/* --- @trace_custom@ --- *
+ *
+ * Arguments:  @void (*func)(const char *buf, size_t sz, void *v)@ =
+ *                     output function
+ *             @void *v@ = magic handle to give to function
+ *
+ * Returns:    ---
+ *
+ * Use:                Sets up a custom trace handler.
+ */
+
+extern void trace_custom(void (*/*func*/)(const char */*buf*/,
+                                         size_t /*sz*/, void */*v*/),
+                        void */*v*/);
+
+/* --- @trace_level@ --- *
+ *
+ * Arguments:  @unsigned l@ = trace level to set
+ *
+ * Returns:    ---
+ *
+ * Use:                Sets the tracing level.
+ */
+
+extern void trace_level(unsigned /*l*/);
+
+/* --- @tracing@ --- *
+ *
+ * Arguments:  ---
+ *
+ * Returns:    Zero if not tracing, tracing level if tracing.
+ *
+ * Use:                Informs the caller whether tracing is enabled.
+ */
+
+extern unsigned tracing(void);
+
+/* --- @traceopt@ --- *
+ *
+ * Arguments:  @const trace_opt *t@ = pointer to trace options table
+ *             @const char *p@ = option string supplied by user
+ *             @unsigned f@ = initial tracing flags
+ *             @unsigned bad@ = forbidden tracing flags
+ *
+ * Returns:    Trace flags as set by user.
+ *
+ * Use:                Parses an option string from the user and sets the
+ *             appropriate trace flags.  If the argument is null or a single
+ *             `?' character, a help message is displayed.
+ */
+
+extern unsigned traceopt(const trace_opt */*t*/, const char */*p*/,
+                        unsigned /*f*/, unsigned /*bad*/);
+
+/*----- Tracing macros ----------------------------------------------------*/
+
+#ifndef NTRACE
+#  define T(x) x
+#  define IF_TRACING(l, x) if ((l) & tracing()) x
+#else
+#  define T(x)
+#  define IF_TRACING(l, x)
+#endif
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif