File: debug.c

package info (click to toggle)
libast 0.7-9
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 2,732 kB
  • sloc: ansic: 13,136; sh: 10,332; makefile: 78
file content (182 lines) | stat: -rw-r--r-- 6,464 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
/*
 * Copyright (C) 1997-2004, Michael Jennings
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies of the Software, its documentation and marketing & publicity
 * materials, and acknowledgment shall be given in the documentation, materials
 * and software packages that this Software was used.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * @file debug.c
 * Debugging Subsystem Source File
 *
 * This file contains all non-cpp-based debugging functionality.
 *
 * @author Michael Jennings <mej@eterm.org>
 * $Revision: 1.14 $
 * $Date: 2004/12/15 00:00:22 $
 */

static const char __attribute__((unused)) cvs_ident[] = "$Id: debug.c,v 1.14 2004/12/15 00:00:22 mej Exp $";

#ifdef HAVE_CONFIG_H
# include <config.h>
#endif

#include "libast_internal.h"

/**
 * Debug level.
 *
 * This variable holds the current debug level.
 *
 * @internal
 * @see DEBUG_LEVEL
 * @ingroup DOXGRP_DEBUG
 */
unsigned int libast_debug_level = 0;
/**
 * Debug flags.
 *
 * This variable holds the current debug flags.  Currently unused.
 *
 * @internal
 * @see DEBUG_FLAGS
 * @ingroup DOXGRP_DEBUG
 */
unsigned long libast_debug_flags = 0;

/**
 * @defgroup DOXGRP_DEBUG Debugging Subsystem
 *
 * This group of functions/defines/macros implements the debugging
 * subsystem within LibAST.
 *
 * LibAST provides a flexible level-based debugging mechanism to
 * client programs, supporting both compile-time and run-time methods
 * for including or suppressing debugging output by increasing or
 * decreasing the "debug level," i.e. the verbosity, of the system.
 *
 * The current level of debugging output is controlled by the
 * DEBUG_LEVEL variable; to alter it, simply assign a new integer
 * value (from 0 to 9, inclusive) to this variable.
 *
 * LibAST provides debugging for several of its own subsystems and
 * allows client applications to use the same debugging mechanisms by
 * defining its own categories. To use the LibAST debugging system,
 * you will need one #define and one macro for each subsystem or
 * debugging category your program will have.
 *
 * For example, let's say your code contains some socket code.  To
 * create a debugging entity for that code, simply add a #define which
 * sets the debug level for it, and a macro to map output messages to
 * the DPRINTF*() macro for that debug level.  If you wanted
 * socket-related debugging information at debug level 2, you'd use
 * something like these:
 *
 * @code
 * #define DEBUG_SOCKETS  2
 * #define D_SOCKETS(x)   DPRINTF2(x)
 * @endcode
 *
 * That's all there is to it!  Now, anywhere you want socket-related
 * debugging output, just use the D_SOCKETS() macro like so:
 *
 * @code
 *     D_SOCKETS(("Connecting to %s...\n", hostname));
 * @endcode
 *
 * Be sure to use TWO sets of parentheses, not just one.  Don't worry;
 * you'll get used to it! :-)
 *
 * That's all there is to it!
 *
 * If you'd like to see a sample program which uses this system, click
 * @link debug_example.c here @endlink.
 */
/**
 * @example debug_example.c
 * Example code for using the debugging subsystem.
 *
 * This is a trivial code example that uses LibAST-style debugging.
 * The program takes a number, a symbol, and another number on the
 * command line to perform simple arithmetic.  Specify the -d option
 * to enable the debugging output.
 *
 * With debugging output turned off (no -d option), you should see
 * something like this:
 *
 * @code
 * $ ./debug_example 4 + 4
 * 4 + 4 = 8
 * $
 * @endcode
 *
 * With debugging output turned on, you should see something like
 * this:
 *
 * @code
 * $ ./debug_example -d 10 - 14
 * [1045855757] debug_example.c |   35: main(): Debugging is now on.
 * [1045855757] debug_example.c |   48: main(): Number 1 is 10
 * [1045855757] debug_example.c |   43: main(): Got operation '-'.
 * [1045855757] debug_example.c |   51: main(): Number 2 is 14
 * 10 - 14 = -4
 * $
 * @endcode
 *
 * As you can see, the debugging output contains UNIX-style time_t
 * timestamps, source file names, line numbers, and function names for
 * each debugging statement.
 *
 * Here's the complete source code:
 */

/* Documentation for the main Doxygen-generated page is here, for no
 * other reason than this file lacks actual code. :-)
 */

/**
 * @mainpage LibAST 0.6.1 Documentation
 *
 * This document describes the various features and capabilities
 * offered by LibAST, the Library of Assorted Spiffy Things.  As its
 * name suggests, LibAST is a collection of various functions, macros,
 * etc. which do all sorts of spiffy stuff.  By reading through all
 * the following pages of goop, hopefully you'll learn about the
 * miscellaneous mounds of spiffitude which await you in LibAST!
 *
 * Choose a section from the list below, or pick one of the quick
 * links at the top of the page.  If you prefer tree-style navigation,
 * there is a hidden frame on the left-hand side of your browser
 * window.  You can expand this frame to find the document tree
 * (requires JavaScript!).
 *
 * @section topiclist Topic List
 *
 * -# @link DOXGRP_TYPES   Portable Data Types @endlink
 * -# @link DOXGRP_DEBUG   Debugging Subsystem @endlink
 * -# @link DOXGRP_MEM     Memory Management Subsystem @endlink
 * -# @link DOXGRP_STRINGS String Utility Routines @endlink
 * -# @link DOXGRP_CONF    Configuration File Parser @endlink
 *   -# @link DOXGRP_CONF_FSS    File State Stack @endlink
 *   -# @link DOXGRP_CONF_CTX    Context Handling @endlink
 * -# @link DOXGRP_OPT     Command Line Option Parser @endlink
 * -# @link DOXGRP_OBJ     Object Infrastructure @endlink
 *
 */