91be73181267df2ddf7449e261f7e38f74a369f6
[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 ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...)
69         __attribute__ ((format (printf, 5, 6)));
70
71 /*! Send a verbose message (based on verbose level)
72         \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
73         ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
74         This will print the message to the console if the verbose level is set to a level >= 3
75         Note the abscence of a comma after the VERBOSE_PREFIX_3.  This is important.
76         VERBOSE_PREFIX_1 through VERBOSE_PREFIX_3 are defined.
77  */
78 void __ast_verbose(const char *file, int line, const char *func, const char *fmt, ...)
79         __attribute__ ((format (printf, 4, 5)));
80
81 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__,  __VA_ARGS__)
82
83 void __ast_verbose_ap(const char *file, int line, const char *func, const char *fmt, va_list ap);
84
85 #define ast_verbose_ap(fmt, ap) __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, ap)
86
87 void ast_child_verbose(int level, const char *fmt, ...)
88         __attribute__ ((format (printf, 2, 3)));
89
90 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
91 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
92
93 void ast_console_puts(const char *string);
94
95 void ast_console_puts_mutable(const char *string, int level);
96 void ast_console_toggle_mute(int fd, int silent);
97 void ast_console_toggle_loglevel(int fd, int leve, int state);
98
99 /* Note: The AST_LOG_* macros below are the same as
100  * the LOG_* macros and are intended to eventually replace
101  * the LOG_* macros to avoid name collisions as has been
102  * seen in app_voicemail. However, please do NOT remove
103  * the LOG_* macros from the source since these may be still
104  * needed for third-party modules
105  */
106
107 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
108
109 #ifdef LOG_DEBUG
110 #undef LOG_DEBUG
111 #endif
112 #define __LOG_DEBUG    0
113 #define LOG_DEBUG      __LOG_DEBUG, _A_
114
115 #ifdef AST_LOG_DEBUG
116 #undef AST_LOG_DEBUG
117 #endif
118 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
119
120 #ifdef LOG_EVENT
121 #undef LOG_EVENT
122 #endif
123 #define __LOG_EVENT    1
124 #define LOG_EVENT      __LOG_EVENT, _A_
125
126 #ifdef AST_LOG_EVENT
127 #undef AST_LOG_EVENT
128 #endif
129 #define AST_LOG_EVENT      __LOG_EVENT, _A_
130
131 #ifdef LOG_NOTICE
132 #undef LOG_NOTICE
133 #endif
134 #define __LOG_NOTICE   2
135 #define LOG_NOTICE     __LOG_NOTICE, _A_
136
137 #ifdef AST_LOG_NOTICE
138 #undef AST_LOG_NOTICE
139 #endif
140 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
141
142 #ifdef LOG_WARNING
143 #undef LOG_WARNING
144 #endif
145 #define __LOG_WARNING  3
146 #define LOG_WARNING    __LOG_WARNING, _A_
147
148 #ifdef AST_LOG_WARNING
149 #undef AST_LOG_WARNING
150 #endif
151 #define AST_LOG_WARNING    __LOG_WARNING, _A_
152
153 #ifdef LOG_ERROR
154 #undef LOG_ERROR
155 #endif
156 #define __LOG_ERROR    4
157 #define LOG_ERROR      __LOG_ERROR, _A_
158
159 #ifdef AST_LOG_ERROR
160 #undef AST_LOG_ERROR
161 #endif
162 #define AST_LOG_ERROR      __LOG_ERROR, _A_
163
164 #ifdef LOG_VERBOSE
165 #undef LOG_VERBOSE
166 #endif
167 #define __LOG_VERBOSE  5
168 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
169
170 #ifdef AST_LOG_VERBOSE
171 #undef AST_LOG_VERBOSE
172 #endif
173 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
174
175 #ifdef LOG_DTMF
176 #undef LOG_DTMF
177 #endif
178 #define __LOG_DTMF  6
179 #define LOG_DTMF    __LOG_DTMF, _A_
180
181 #ifdef AST_LOG_DTMF
182 #undef AST_LOG_DTMF
183 #endif
184 #define AST_LOG_DTMF    __LOG_DTMF, _A_
185
186 #define NUMLOGLEVELS 6
187
188 /*!
189  * \brief Get the debug level for a file
190  * \param file the filename
191  * \return the debug level
192  */
193 unsigned int ast_debug_get_by_file(const char *file);
194
195 /*!
196  * \brief Get the debug level for a file
197  * \param file the filename
198  * \return the debug level
199  */
200 unsigned int ast_verbose_get_by_file(const char *file);
201
202 /*!
203  * \brief Log a DEBUG message
204  * \param level The minimum value of option_debug for this message
205  *        to get logged
206  */
207 #define ast_debug(level, ...) do {       \
208         if (option_debug >= (level) || (ast_opt_dbg_file && ast_debug_get_by_file(__FILE__) >= (level)) ) \
209                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
210 } while (0)
211
212 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_file && ast_verbose_get_by_file(__FILE__) >= (level)))
213
214 #define ast_verb(level, ...) do { \
215         if (VERBOSITY_ATLEAST((level)) ) { \
216                 if (level >= 4) \
217                         ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
218                 else if (level == 3) \
219                         ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
220                 else if (level == 2) \
221                         ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
222                 else if (level == 1) \
223                         ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
224                 else \
225                         ast_verbose(__VA_ARGS__); \
226         } \
227 } while (0)
228
229 #ifndef _LOGGER_BACKTRACE_H
230 #define _LOGGER_BACKTRACE_H
231 #ifdef HAVE_BKTR
232 #define AST_MAX_BT_FRAMES 32
233 /* \brief
234  *
235  * A structure to hold backtrace information. This structure provides an easy means to 
236  * store backtrace information or pass backtraces to other functions.
237  */
238 struct ast_bt {
239         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
240         void *addresses[AST_MAX_BT_FRAMES];
241         /*! The number of stack frames in the backtrace */
242         int num_frames;
243         /*! Tells if the ast_bt structure was dynamically allocated */
244         unsigned int alloced:1;
245 };
246
247 /* \brief
248  * Allocates memory for an ast_bt and stores addresses and symbols.
249  *
250  * \return Returns NULL on failure, or the allocated ast_bt on success
251  */
252 struct ast_bt *ast_bt_create(void);
253
254 /* \brief
255  * Fill an allocated ast_bt with addresses
256  *
257  * \retval 0 Success
258  * \retval -1 Failure
259  */
260 int ast_bt_get_addresses(struct ast_bt *bt);
261
262 /* \brief
263  * 
264  * Free dynamically allocated portions of an ast_bt
265  *
266  * \retval NULL.
267  */
268 void *ast_bt_destroy(struct ast_bt *bt);
269
270 #endif /* HAVE_BKTR */
271 #endif /* _LOGGER_BACKTRACE_H */
272
273 #if defined(__cplusplus) || defined(c_plusplus)
274 }
275 #endif
276
277 #endif /* _ASTERISK_LOGGER_H */