debug Explain the behaviour of setup_logging() more clearly
[sfrench/samba-autobuild/.git] / source3 / include / debug.h
1 /* 
2    Unix SMB/CIFS implementation.
3    SMB debug stuff
4    Copyright (C) Andrew Tridgell 1992-1998
5    Copyright (C) John H Terpstra 1996-1998
6    Copyright (C) Luke Kenneth Casson Leighton 1996-1998
7    Copyright (C) Paul Ashton 1998
8
9    This program is free software; you can redistribute it and/or modify
10    it under the terms of the GNU General Public License as published by
11    the Free Software Foundation; either version 3 of the License, or
12    (at your option) any later version.
13
14    This program is distributed in the hope that it will be useful,
15    but WITHOUT ANY WARRANTY; without even the implied warranty of
16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17    GNU General Public License for more details.
18
19    You should have received a copy of the GNU General Public License
20    along with this program.  If not, see <http://www.gnu.org/licenses/>.
21 */
22
23 #ifndef _DEBUG_H
24 #define _DEBUG_H
25
26 /* -------------------------------------------------------------------------- **
27  * Debugging code.  See also debug.c
28  */
29
30 /* the maximum debug level to compile into the code. This assumes a good
31    optimising compiler that can remove unused code
32    for embedded or low-memory systems set this to a value like 2 to get
33    only important messages. This gives *much* smaller binaries
34 */
35 #ifndef MAX_DEBUG_LEVEL
36 #define MAX_DEBUG_LEVEL 1000
37 #endif
38
39 /* mkproto.awk has trouble with ifdef'd function definitions (it ignores
40  * the #ifdef directive and will read both definitions, thus creating two
41  * diffferent prototype declarations), so we must do these by hand.
42  */
43 /* I know the __attribute__ stuff is ugly, but it does ensure we get the 
44    arguments to DEBUG() right. We have got them wrong too often in the 
45    past.
46    The PRINTFLIKE comment does the equivalent for SGI MIPSPro.
47  */
48 /* PRINTFLIKE1 */
49 int  Debug1( const char *, ... ) PRINTF_ATTRIBUTE(1,2);
50 /* PRINTFLIKE1 */
51 bool dbgtext( const char *, ... ) PRINTF_ATTRIBUTE(1,2);
52 bool dbghdrclass( int level, int cls, const char *location, const char *func);
53 bool dbghdr( int level, const char *location, const char *func);
54
55 #if defined(sgi) && (_COMPILER_VERSION >= 730)
56 #pragma mips_frequency_hint NEVER Debug1
57 #pragma mips_frequency_hint NEVER dbgtext
58 #pragma mips_frequency_hint NEVER dbghdrclass
59 #pragma mips_frequency_hint NEVER dbghdr
60 #endif
61
62 /* If we have these macros, we can add additional info to the header. */
63
64 #ifdef HAVE_FUNCTION_MACRO
65 #define FUNCTION_MACRO  (__FUNCTION__)
66 #else
67 #define FUNCTION_MACRO  ("")
68 #endif
69
70 /* 
71  * Redefine DEBUGLEVEL because so we don't have to change every source file
72  * that *unnecessarily* references it. Source files neeed not extern reference 
73  * DEBUGLEVEL, as it's extern in includes.h (which all source files include).
74  * Eventually, all these references should be removed, and all references to
75  * DEBUGLEVEL should be references to DEBUGLEVEL_CLASS[DBGC_ALL]. This could
76  * still be through a macro still called DEBUGLEVEL. This cannot be done now
77  * because some references would expand incorrectly.
78  */
79 #define DEBUGLEVEL *debug_level
80 extern int DEBUGLEVEL;
81
82 /*
83  * Define all new debug classes here. A class is represented by an entry in
84  * the DEBUGLEVEL_CLASS array. Index zero of this arrray is equivalent to the
85  * old DEBUGLEVEL. Any source file that does NOT add the following lines:
86  *
87  *   #undef  DBGC_CLASS
88  *   #define DBGC_CLASS DBGC_<your class name here>
89  *
90  * at the start of the file (after #include "includes.h") will default to
91  * using index zero, so it will behaive just like it always has. 
92  */
93 #define DBGC_ALL                0 /* index equivalent to DEBUGLEVEL */
94
95 #define DBGC_TDB                1
96 #define DBGC_PRINTDRIVERS       2
97 #define DBGC_LANMAN             3
98 #define DBGC_SMB                4
99 #define DBGC_RPC_PARSE          5
100 #define DBGC_RPC_SRV            6
101 #define DBGC_RPC_CLI            7
102 #define DBGC_PASSDB             8
103 #define DBGC_SAM                9
104 #define DBGC_AUTH               10
105 #define DBGC_WINBIND            11
106 #define DBGC_VFS                12
107 #define DBGC_IDMAP              13
108 #define DBGC_QUOTA              14
109 #define DBGC_ACLS               15
110 #define DBGC_LOCKING            16
111 #define DBGC_MSDFS              17
112 #define DBGC_DMAPI              18
113 #define DBGC_REGISTRY           19
114
115 /* So you can define DBGC_CLASS before including debug.h */
116 #ifndef DBGC_CLASS
117 #define DBGC_CLASS            0     /* override as shown above */
118 #endif
119
120 extern int  *DEBUGLEVEL_CLASS;
121 extern bool *DEBUGLEVEL_CLASS_ISSET;
122
123 /* Debugging macros
124  *
125  * DEBUGLVL()
126  *   If the 'file specific' debug class level >= level OR the system-wide 
127  *   DEBUGLEVEL (synomym for DEBUGLEVEL_CLASS[ DBGC_ALL ]) >= level then
128  *   generate a header using the default macros for file, line, and 
129  *   function name. Returns True if the debug level was <= DEBUGLEVEL.
130  * 
131  *   Example: if( DEBUGLVL( 2 ) ) dbgtext( "Some text.\n" );
132  *
133  * DEBUGLVLC()
134  *   If the 'macro specified' debug class level >= level OR the system-wide 
135  *   DEBUGLEVEL (synomym for DEBUGLEVEL_CLASS[ DBGC_ALL ]) >= level then 
136  *   generate a header using the default macros for file, line, and 
137  *   function name. Returns True if the debug level was <= DEBUGLEVEL.
138  * 
139  *   Example: if( DEBUGLVLC( DBGC_TDB, 2 ) ) dbgtext( "Some text.\n" );
140  *
141  * DEBUG()
142  *   If the 'file specific' debug class level >= level OR the system-wide 
143  *   DEBUGLEVEL (synomym for DEBUGLEVEL_CLASS[ DBGC_ALL ]) >= level then 
144  *   generate a header using the default macros for file, line, and 
145  *   function name. Each call to DEBUG() generates a new header *unless* the 
146  *   previous debug output was unterminated (i.e. no '\n').
147  *   See debug.c:dbghdr() for more info.
148  *
149  *   Example: DEBUG( 2, ("Some text and a value %d.\n", value) );
150  *
151  * DEBUGC()
152  *   If the 'macro specified' debug class level >= level OR the system-wide 
153  *   DEBUGLEVEL (synomym for DEBUGLEVEL_CLASS[ DBGC_ALL ]) >= level then 
154  *   generate a header using the default macros for file, line, and 
155  *   function name. Each call to DEBUG() generates a new header *unless* the 
156  *   previous debug output was unterminated (i.e. no '\n').
157  *   See debug.c:dbghdr() for more info.
158  *
159  *   Example: DEBUGC( DBGC_TDB, 2, ("Some text and a value %d.\n", value) );
160  *
161  *  DEBUGADD(), DEBUGADDC()
162  *    Same as DEBUG() and DEBUGC() except the text is appended to the previous
163  *    DEBUG(), DEBUGC(), DEBUGADD(), DEBUGADDC() with out another interviening 
164  *    header.
165  *
166  *    Example: DEBUGADD( 2, ("Some text and a value %d.\n", value) );
167  *             DEBUGADDC( DBGC_TDB, 2, ("Some text and a value %d.\n", value) );
168  *
169  * Note: If the debug class has not be redeined (see above) then the optimizer 
170  * will remove the extra conditional test.
171  */
172
173 /*
174  * From talloc.c:
175  */
176
177 /* these macros gain us a few percent of speed on gcc */
178 #if (__GNUC__ >= 3)
179 /* the strange !! is to ensure that __builtin_expect() takes either 0 or 1
180    as its first argument */
181 #ifndef likely
182 #define likely(x)   __builtin_expect(!!(x), 1)
183 #endif
184 #ifndef unlikely
185 #define unlikely(x) __builtin_expect(!!(x), 0)
186 #endif
187 #else
188 #ifndef likely
189 #define likely(x) (x)
190 #endif
191 #ifndef unlikely
192 #define unlikely(x) (x)
193 #endif
194 #endif
195
196 #define CHECK_DEBUGLVL( level ) \
197   ( ((level) <= MAX_DEBUG_LEVEL) && \
198      unlikely((DEBUGLEVEL_CLASS[ DBGC_CLASS ] >= (level))||  \
199      (!DEBUGLEVEL_CLASS_ISSET[ DBGC_CLASS ] && \
200       DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) )
201
202 #define DEBUGLVL( level ) \
203   ( CHECK_DEBUGLVL(level) \
204    && dbghdrclass( level, DBGC_CLASS, __location__, FUNCTION_MACRO ) )
205
206
207 #define DEBUGLVLC( dbgc_class, level ) \
208   ( ((level) <= MAX_DEBUG_LEVEL) && \
209      unlikely((DEBUGLEVEL_CLASS[ dbgc_class ] >= (level))||  \
210      (!DEBUGLEVEL_CLASS_ISSET[ dbgc_class ] && \
211       DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) \
212    && dbghdrclass( level, DBGC_CLASS, __location__, FUNCTION_MACRO) )
213
214
215 #define DEBUG( level, body ) \
216   (void)( ((level) <= MAX_DEBUG_LEVEL) && \
217            unlikely((DEBUGLEVEL_CLASS[ DBGC_CLASS ] >= (level))||  \
218            (!DEBUGLEVEL_CLASS_ISSET[ DBGC_CLASS ] && \
219             DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) \
220        && (dbghdrclass( level, DBGC_CLASS, __location__, FUNCTION_MACRO )) \
221        && (dbgtext body) )
222
223 #define DEBUGC( dbgc_class, level, body ) \
224   (void)( ((level) <= MAX_DEBUG_LEVEL) && \
225            unlikely((DEBUGLEVEL_CLASS[ dbgc_class ] >= (level))||  \
226            (!DEBUGLEVEL_CLASS_ISSET[ dbgc_class ] && \
227             DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) \
228        && (dbghdrclass( level, DBGC_CLASS, __location__, FUNCTION_MACRO)) \
229        && (dbgtext body) )
230
231 #define DEBUGADD( level, body ) \
232   (void)( ((level) <= MAX_DEBUG_LEVEL) && \
233            unlikely((DEBUGLEVEL_CLASS[ DBGC_CLASS ] >= (level))||  \
234            (!DEBUGLEVEL_CLASS_ISSET[ DBGC_CLASS ] && \
235             DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) \
236        && (dbgtext body) )
237
238 #define DEBUGADDC( dbgc_class, level, body ) \
239   (void)( ((level) <= MAX_DEBUG_LEVEL) && \
240           unlikely((DEBUGLEVEL_CLASS[ dbgc_class ] >= (level))||  \
241            (!DEBUGLEVEL_CLASS_ISSET[ dbgc_class ] && \
242             DEBUGLEVEL_CLASS[ DBGC_ALL   ] >= (level))  ) \
243        && (dbgtext body) )
244
245 /* Print a separator to the debug log. */
246 #define DEBUGSEP(level)\
247         DEBUG((level),("===============================================================\n"))
248
249 /* The following definitions come from lib/debug.c  */
250
251 /** Possible destinations for the debug log (in order of precedence -
252  * once set to DEBUG_FILE, it is not possible to reset to DEBUG_STDOUT
253  * for example.  This makes it easy to override for debug to stderr on
254  * the command line, as the smb.conf cannot reset it back to
255  * file-based logging */
256 enum debug_logtype {DEBUG_DEFAULT_STDERR = 0, DEBUG_STDOUT = 1, DEBUG_FILE = 2, DEBUG_STDERR = 3};
257
258 void setup_logging(const char *prog_name, enum debug_logtype new_logtype);
259
260 void debug_close_dbf(void);
261 void gfree_debugsyms(void);
262 const char *debug_classname_from_index(int ndx);
263 int debug_add_class(const char *classname);
264 int debug_lookup_classname(const char *classname);
265 bool debug_parse_levels(const char *params_str);
266 void debug_message(struct messaging_context *msg_ctx, void *private_data, uint32_t msg_type, struct server_id src, DATA_BLOB *data);
267 void debug_init(void);
268 void debug_register_msgs(struct messaging_context *msg_ctx);
269 void debug_set_logfile(const char *name);
270 bool reopen_logs( void );
271 void force_check_log_size( void );
272 bool need_to_check_log_size( void );
273 void check_log_size( void );
274 void dbgflush( void );
275 bool dbghdrclass(int level, int cls, const char *location, const char *func);
276 bool dbghdr(int level, const char *location, const char *func);
277
278 #endif
279