Add backtrace generation to MALLOC_DEBUG memory corruption reports
[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 #define AST_CALLID_BUFFER_LENGTH 13
47
48 /*! \brief Used for sending a log message
49         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
50         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
51         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
52         on which log you wish to output to. These are implemented as macros, that
53         will provide the function with the needed arguments.
54
55         \param level    Type of log event
56         \param file     Will be provided by the AST_LOG_* macro
57         \param line     Will be provided by the AST_LOG_* macro
58         \param function Will be provided by the AST_LOG_* macro
59         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
60  */
61
62 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
63         __attribute__((format(printf, 5, 6)));
64
65 /* XXX needs documentation */
66 struct ast_callid;
67
68 /*! \brief Used for sending a log message with a known call_id
69         This is a modified logger function which is functionally identical to the above logger function,
70         it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
71         join the log message with a call_id.
72
73         \param level    Type of log event
74         \param file     Will be provided by the AST_LOG_* macro
75         \param line     Will be provided by the AST_LOG_* macro
76         \param function Will be provided by the AST_LOG_* macro
77         \param callid   This is the ast_callid that is associated with the log message. May be NULL.
78         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
79 */
80 void ast_log_callid(int level, const char *file, int line, const char *function, struct ast_callid *callid, const char *fmt, ...)
81         __attribute__((format(printf, 6, 7)));
82
83 /*!
84  * \brief Log a backtrace of the current thread's execution stack to the Asterisk log
85  */
86 void ast_log_backtrace(void);
87
88 /*! \brief Reload logger without rotating log files */
89 int logger_reload(void);
90
91 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
92
93 /*! Send a verbose message (based on verbose level)
94  *      \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
95  *      ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
96  *      This will print the message to the console if the verbose level is set to a level >= 3
97  *      Note the absence of a comma after the VERBOSE_PREFIX_3.  This is important.
98  *      VERBOSE_PREFIX_1 through VERBOSE_PREFIX_4 are defined.
99  *  \version 11 added level parameter
100  */
101 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
102
103 /*! Send a verbose message (based on verbose level) with deliberately specified callid
104  *  \brief just like __ast_verbose, only __ast_verbose_callid allows you to specify which callid is being used
105  *  for the log without needing to bind it to a thread. NULL is a valid argument for this function and will
106  *  allow you to specify that a log will never display a call id even when there is a call id bound to the
107  *  thread.
108  */
109 void __attribute__((format(printf, 6, 7))) __ast_verbose_callid(const char *file, int line, const char *func, int level, struct ast_callid *callid, const char *fmt, ...);
110
111 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, __VA_ARGS__)
112 #define ast_verbose_callid(callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, callid, __VA_ARGS__)
113
114 void __attribute__((format(printf, 6, 0))) __ast_verbose_ap(const char *file, int line, const char *func, int level, struct ast_callid *callid, const char *fmt, va_list ap);
115
116 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
117
118 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
119 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
120
121 void ast_console_puts(const char *string);
122
123 /*!
124  * \brief log the string to the console, and all attached
125  * console clients
126  * \version 1.6.1 added level parameter
127  */
128 void ast_console_puts_mutable(const char *string, int level);
129 void ast_console_toggle_mute(int fd, int silent);
130
131 /*!
132  * \brief enables or disables logging of a specified level to the console
133  * fd specifies the index of the console receiving the level change
134  * level specifies the index of the logging level being toggled
135  * state indicates whether logging will be on or off (0 for off, 1 for on)
136  */
137 void ast_console_toggle_loglevel(int fd, int level, int state);
138
139 /* Note: The AST_LOG_* macros below are the same as
140  * the LOG_* macros and are intended to eventually replace
141  * the LOG_* macros to avoid name collisions with the syslog(3)
142  * log levels. However, please do NOT remove
143  * the LOG_* macros from the source since these may be still
144  * needed for third-party modules
145  */
146
147 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
148
149 #ifdef LOG_DEBUG
150 #undef LOG_DEBUG
151 #endif
152 #define __LOG_DEBUG    0
153 #define LOG_DEBUG      __LOG_DEBUG, _A_
154
155 #ifdef AST_LOG_DEBUG
156 #undef AST_LOG_DEBUG
157 #endif
158 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
159
160 #ifdef LOG_NOTICE
161 #undef LOG_NOTICE
162 #endif
163 #define __LOG_NOTICE   2
164 #define LOG_NOTICE     __LOG_NOTICE, _A_
165
166 #ifdef AST_LOG_NOTICE
167 #undef AST_LOG_NOTICE
168 #endif
169 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
170
171 #ifdef LOG_WARNING
172 #undef LOG_WARNING
173 #endif
174 #define __LOG_WARNING  3
175 #define LOG_WARNING    __LOG_WARNING, _A_
176
177 #ifdef AST_LOG_WARNING
178 #undef AST_LOG_WARNING
179 #endif
180 #define AST_LOG_WARNING    __LOG_WARNING, _A_
181
182 #ifdef LOG_ERROR
183 #undef LOG_ERROR
184 #endif
185 #define __LOG_ERROR    4
186 #define LOG_ERROR      __LOG_ERROR, _A_
187
188 #ifdef AST_LOG_ERROR
189 #undef AST_LOG_ERROR
190 #endif
191 #define AST_LOG_ERROR      __LOG_ERROR, _A_
192
193 #ifdef LOG_VERBOSE
194 #undef LOG_VERBOSE
195 #endif
196 #define __LOG_VERBOSE  5
197 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
198
199 #ifdef AST_LOG_VERBOSE
200 #undef AST_LOG_VERBOSE
201 #endif
202 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
203
204 #ifdef LOG_DTMF
205 #undef LOG_DTMF
206 #endif
207 #define __LOG_DTMF  6
208 #define LOG_DTMF    __LOG_DTMF, _A_
209
210 #ifdef AST_LOG_DTMF
211 #undef AST_LOG_DTMF
212 #endif
213 #define AST_LOG_DTMF    __LOG_DTMF, _A_
214
215 #define NUMLOGLEVELS 32
216
217 /*!
218  * \brief Get the debug level for a module
219  * \param module the name of module
220  * \return the debug level
221  */
222 unsigned int ast_debug_get_by_module(const char *module);
223
224 /*!
225  * \brief Get the verbose level for a module
226  * \param module the name of module
227  * \return the verbose level
228  */
229 unsigned int ast_verbose_get_by_module(const char *module);
230
231 /*!
232  * \brief Register a new logger level
233  * \param name The name of the level to be registered
234  * \retval -1 if an error occurs
235  * \retval non-zero level to be used with ast_log for sending messages to this level
236  * \since 1.8
237  */
238 int ast_logger_register_level(const char *name);
239
240 /*!
241  * \brief Unregister a previously registered logger level
242  * \param name The name of the level to be unregistered
243  * \return nothing
244  * \since 1.8
245  */
246 void ast_logger_unregister_level(const char *name);
247
248 /*!
249  * \brief factory function to create a new uniquely identifying callid.
250  *
251  * \retval ast_callid struct pointer containing the call id
252  *
253  * \note The newly created callid will be referenced upon creation and this function should be
254  * paired with a call to ast_callid_unref()
255  */
256 struct ast_callid *ast_create_callid(void);
257
258 /*!
259  * \brief extracts the callerid from the thread
260  *
261  * \retval ast_callid reference to call_id related to the thread
262  * \retval NULL if no call_id is present in the thread
263  *
264  * This reference must be unreffed before it loses scope to prevent memory leaks.
265  */
266 struct ast_callid *ast_read_threadstorage_callid(void);
267
268 /*!
269  * \brief Increase callid reference count
270  *
271  * \param c the ast_callid
272  *
273  * \retval c always
274  */
275 #define ast_callid_ref(c) ({ ao2_ref(c, +1); (c); })
276
277 /*!
278  * \brief Decrease callid reference count
279  *
280  * \param c the ast_callid
281  *
282  * \retval NULL always
283  */
284 #define ast_callid_unref(c) ({ ao2_ref(c, -1); (NULL); })
285
286 /*!
287  * \brief Sets what is stored in the thread storage to the given
288  *        callid if it does not match what is already there.
289  *
290  * \retval 0 - success
291  * \retval non-zero - failure
292  */
293 int ast_callid_threadassoc_change(struct ast_callid *callid);
294
295 /*!
296  * \brief Adds a known callid to thread storage of the calling thread
297  *
298  * \retval 0 - success
299  * \retval non-zero - failure
300  */
301 int ast_callid_threadassoc_add(struct ast_callid *callid);
302
303 /*!
304  * \brief Removes callid from thread storage of the calling thread
305  *
306  * \retval 0 - success
307  * \retval non-zero - failure
308  */
309 int ast_callid_threadassoc_remove(void);
310
311 /*!
312  * \brief Checks thread storage for a callid and stores a reference if it exists.
313  *        If not, then a new one will be created, bound to the thread, and a reference
314  *        to it will be stored.
315  *
316  * \param callid pointer to struct pointer used to store the referenced callid
317  * \retval 0 - callid was found
318  * \retval 1 - callid was created
319  * \retval -1 - the function failed somehow (presumably memory problems)
320  */
321 int ast_callid_threadstorage_auto(struct ast_callid **callid);
322
323 /*!
324  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
325  *        references and if the callid was created by threadstorage_auto, unbinds
326  *        the callid from the threadstorage
327  * \param callid The callid set by ast_callid_threadstorage_auto
328  * \param callid_created The integer returned through ast_callid_threadstorage_auto
329  */
330 void ast_callid_threadstorage_auto_clean(struct ast_callid *callid, int callid_created);
331
332 /*!
333  * \brief copy a string representation of the callid into a target string
334  *
335  * \param buffer destination of callid string (should be able to store 13 characters or more)
336  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
337  * \param callid Callid for which string is being requested
338  */
339 void ast_callid_strnprint(char *buffer, size_t buffer_size, struct ast_callid *callid);
340
341 /*!
342  * \brief Send a log message to a dynamically registered log level
343  * \param level The log level to send the message to
344  *
345  * Like ast_log, the log message may include printf-style formats, and
346  * the data for these must be provided as additional parameters after
347  * the log message.
348  *
349  * \return nothing
350  * \since 1.8
351  */
352
353 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
354
355 /*!
356  * \brief Log a DEBUG message
357  * \param level The minimum value of option_debug for this message
358  *        to get logged
359  */
360 #define ast_debug(level, ...) do {       \
361         if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
362                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
363 } while (0)
364
365 #define ast_verb(level, ...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__)
366 #define ast_verb_callid(level, callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, callid, __VA_ARGS__)
367
368 #if defined(__cplusplus) || defined(c_plusplus)
369 }
370 #endif
371
372 #endif /* _ASTERISK_LOGGER_H */