incorporates r159808 from branches/1.4:
[asterisk/asterisk.git] / include / asterisk / logger.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20   \file logger.h
21   \brief Support for logging to various files, console and syslog
22         Configuration in file logger.conf
23 */
24
25 #ifndef _ASTERISK_LOGGER_H
26 #define _ASTERISK_LOGGER_H
27
28 #include "asterisk/options.h"   /* need option_debug */
29
30 #if defined(__cplusplus) || defined(c_plusplus)
31 extern "C" {
32 #endif
33
34 #define EVENTLOG "event_log"
35 #define QUEUELOG        "queue_log"
36
37 #define DEBUG_M(a) { \
38         a; \
39 }
40
41 #define VERBOSE_PREFIX_1 " "
42 #define VERBOSE_PREFIX_2 "  == "
43 #define VERBOSE_PREFIX_3 "    -- "
44 #define VERBOSE_PREFIX_4 "       > "
45
46 /*! \brief Used for sending a log message 
47         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
48         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
49         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
50         on which log you wish to output to. These are implemented as macros, that
51         will provide the function with the needed arguments.
52
53         \param level    Type of log event
54         \param file     Will be provided by the AST_LOG_* macro
55         \param line     Will be provided by the AST_LOG_* macro
56         \param function Will be provided by the AST_LOG_* macro
57         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
58  */
59
60 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
61         __attribute__((format(printf, 5, 6)));
62
63 void ast_backtrace(void);
64
65 /*! \brief Reload logger without rotating log files */
66 int logger_reload(void);
67
68 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
69
70 /*! Send a verbose message (based on verbose level)
71         \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
72         ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
73         This will print the message to the console if the verbose level is set to a level >= 3
74         Note the abscence of a comma after the VERBOSE_PREFIX_3.  This is important.
75         VERBOSE_PREFIX_1 through VERBOSE_PREFIX_3 are defined.
76  */
77 void __attribute__((format(printf, 4, 5))) __ast_verbose(const char *file, int line, const char *func, const char *fmt, ...);
78
79 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__,  __VA_ARGS__)
80
81 void __attribute__((format(printf, 4, 0))) __ast_verbose_ap(const char *file, int line, const char *func, const char *fmt, va_list ap);
82
83 #define ast_verbose_ap(fmt, ap) __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, ap)
84
85 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
86
87 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
88 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
89
90 void ast_console_puts(const char *string);
91
92 void ast_console_puts_mutable(const char *string, int level);
93 void ast_console_toggle_mute(int fd, int silent);
94 void ast_console_toggle_loglevel(int fd, int leve, int state);
95
96 /* Note: The AST_LOG_* macros below are the same as
97  * the LOG_* macros and are intended to eventually replace
98  * the LOG_* macros to avoid name collisions as has been
99  * seen in app_voicemail. However, please do NOT remove
100  * the LOG_* macros from the source since these may be still
101  * needed for third-party modules
102  */
103
104 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
105
106 #ifdef LOG_DEBUG
107 #undef LOG_DEBUG
108 #endif
109 #define __LOG_DEBUG    0
110 #define LOG_DEBUG      __LOG_DEBUG, _A_
111
112 #ifdef AST_LOG_DEBUG
113 #undef AST_LOG_DEBUG
114 #endif
115 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
116
117 #ifdef LOG_EVENT
118 #undef LOG_EVENT
119 #endif
120 #define __LOG_EVENT    1
121 #define LOG_EVENT      __LOG_EVENT, _A_
122
123 #ifdef AST_LOG_EVENT
124 #undef AST_LOG_EVENT
125 #endif
126 #define AST_LOG_EVENT      __LOG_EVENT, _A_
127
128 #ifdef LOG_NOTICE
129 #undef LOG_NOTICE
130 #endif
131 #define __LOG_NOTICE   2
132 #define LOG_NOTICE     __LOG_NOTICE, _A_
133
134 #ifdef AST_LOG_NOTICE
135 #undef AST_LOG_NOTICE
136 #endif
137 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
138
139 #ifdef LOG_WARNING
140 #undef LOG_WARNING
141 #endif
142 #define __LOG_WARNING  3
143 #define LOG_WARNING    __LOG_WARNING, _A_
144
145 #ifdef AST_LOG_WARNING
146 #undef AST_LOG_WARNING
147 #endif
148 #define AST_LOG_WARNING    __LOG_WARNING, _A_
149
150 #ifdef LOG_ERROR
151 #undef LOG_ERROR
152 #endif
153 #define __LOG_ERROR    4
154 #define LOG_ERROR      __LOG_ERROR, _A_
155
156 #ifdef AST_LOG_ERROR
157 #undef AST_LOG_ERROR
158 #endif
159 #define AST_LOG_ERROR      __LOG_ERROR, _A_
160
161 #ifdef LOG_VERBOSE
162 #undef LOG_VERBOSE
163 #endif
164 #define __LOG_VERBOSE  5
165 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
166
167 #ifdef AST_LOG_VERBOSE
168 #undef AST_LOG_VERBOSE
169 #endif
170 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
171
172 #ifdef LOG_DTMF
173 #undef LOG_DTMF
174 #endif
175 #define __LOG_DTMF  6
176 #define LOG_DTMF    __LOG_DTMF, _A_
177
178 #ifdef AST_LOG_DTMF
179 #undef AST_LOG_DTMF
180 #endif
181 #define AST_LOG_DTMF    __LOG_DTMF, _A_
182
183 #define NUMLOGLEVELS 6
184
185 /*!
186  * \brief Get the debug level for a file
187  * \param file the filename
188  * \return the debug level
189  */
190 unsigned int ast_debug_get_by_file(const char *file);
191
192 /*!
193  * \brief Get the debug level for a file
194  * \param file the filename
195  * \return the debug level
196  */
197 unsigned int ast_verbose_get_by_file(const char *file);
198
199 /*!
200  * \brief Log a DEBUG message
201  * \param level The minimum value of option_debug for this message
202  *        to get logged
203  */
204 #define ast_debug(level, ...) do {       \
205         if (option_debug >= (level) || (ast_opt_dbg_file && ast_debug_get_by_file(__FILE__) >= (level)) ) \
206                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
207 } while (0)
208
209 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_file && ast_verbose_get_by_file(__FILE__) >= (level)))
210
211 #define ast_verb(level, ...) do { \
212         if (VERBOSITY_ATLEAST((level)) ) { \
213                 if (level >= 4) \
214                         ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
215                 else if (level == 3) \
216                         ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
217                 else if (level == 2) \
218                         ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
219                 else if (level == 1) \
220                         ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
221                 else \
222                         ast_verbose(__VA_ARGS__); \
223         } \
224 } while (0)
225
226 #ifndef _LOGGER_BACKTRACE_H
227 #define _LOGGER_BACKTRACE_H
228 #ifdef HAVE_BKTR
229 #define AST_MAX_BT_FRAMES 32
230 /* \brief
231  *
232  * A structure to hold backtrace information. This structure provides an easy means to 
233  * store backtrace information or pass backtraces to other functions.
234  */
235 struct ast_bt {
236         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
237         void *addresses[AST_MAX_BT_FRAMES];
238         /*! The number of stack frames in the backtrace */
239         int num_frames;
240         /*! Tells if the ast_bt structure was dynamically allocated */
241         unsigned int alloced:1;
242 };
243
244 /* \brief
245  * Allocates memory for an ast_bt and stores addresses and symbols.
246  *
247  * \return Returns NULL on failure, or the allocated ast_bt on success
248  */
249 struct ast_bt *ast_bt_create(void);
250
251 /* \brief
252  * Fill an allocated ast_bt with addresses
253  *
254  * \retval 0 Success
255  * \retval -1 Failure
256  */
257 int ast_bt_get_addresses(struct ast_bt *bt);
258
259 /* \brief
260  * 
261  * Free dynamically allocated portions of an ast_bt
262  *
263  * \retval NULL.
264  */
265 void *ast_bt_destroy(struct ast_bt *bt);
266
267 #endif /* HAVE_BKTR */
268 #endif /* _LOGGER_BACKTRACE_H */
269
270 #if defined(__cplusplus) || defined(c_plusplus)
271 }
272 #endif
273
274 #endif /* _ASTERISK_LOGGER_H */