Various bug fixes: understand requests for help properly, and fix the

[mLib] / trace.h

/* -*-c-*-
 *
 * $Id: trace.h,v 1.6 2001/02/03 16:23:55 mdw Exp $
 *
 * 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.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: trace.h,v $
 * Revision 1.6  2001/02/03 16:23:55  mdw
 * New custom trace output interface.
 *
 * Revision 1.5  1999/12/10 23:42:04  mdw
 * Change header file guard names.
 *
 * Revision 1.4  1999/10/22 22:39:52  mdw
 * New documented interface for tracing.
 *
 * Revision 1.3  1999/05/06 19:51:35  mdw
 * Reformatted the LGPL notice a little bit.
 *
 * Revision 1.2  1999/05/05 18:50:31  mdw
 * Change licensing conditions to LGPL.
 *
 * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
 * Initial version of mLib
 *
 */

#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