Mon Oct 8 12:39:03 2012

Asterisk developer's documentation


logger.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020   \file logger.h
00021   \brief Support for logging to various files, console and syslog
00022    Configuration in file logger.conf
00023 */
00024 
00025 #ifndef _ASTERISK_LOGGER_H
00026 #define _ASTERISK_LOGGER_H
00027 
00028 #include "asterisk/options.h" /* need option_debug */
00029 
00030 #if defined(__cplusplus) || defined(c_plusplus)
00031 extern "C" {
00032 #endif
00033 
00034 #define EVENTLOG "event_log"
00035 #define  QUEUELOG "queue_log"
00036 
00037 #define DEBUG_M(a) { \
00038    a; \
00039 }
00040 
00041 #define VERBOSE_PREFIX_1 " "
00042 #define VERBOSE_PREFIX_2 "  == "
00043 #define VERBOSE_PREFIX_3 "    -- "
00044 #define VERBOSE_PREFIX_4 "       > "
00045 
00046 /*! \brief Used for sending a log message
00047    This is the standard logger function.  Probably the only way you will invoke it would be something like this:
00048    ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
00049    where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
00050    on which log you wish to output to. These are implemented as macros, that
00051    will provide the function with the needed arguments.
00052 
00053    \param level   Type of log event
00054    \param file Will be provided by the AST_LOG_* macro
00055    \param line Will be provided by the AST_LOG_* macro
00056    \param function   Will be provided by the AST_LOG_* macro
00057    \param fmt  This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
00058  */
00059 
00060 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
00061    __attribute__((format(printf, 5, 6)));
00062 
00063 void ast_backtrace(void);
00064 
00065 /*! \brief Reload logger without rotating log files */
00066 int logger_reload(void);
00067 
00068 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
00069 
00070 /*! Send a verbose message (based on verbose level)
00071    \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
00072    ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
00073    This will print the message to the console if the verbose level is set to a level >= 3
00074    Note the abscence of a comma after the VERBOSE_PREFIX_3.  This is important.
00075    VERBOSE_PREFIX_1 through VERBOSE_PREFIX_3 are defined.
00076  */
00077 void __attribute__((format(printf, 4, 5))) __ast_verbose(const char *file, int line, const char *func, const char *fmt, ...);
00078 
00079 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__,  __VA_ARGS__)
00080 
00081 void __attribute__((format(printf, 4, 0))) __ast_verbose_ap(const char *file, int line, const char *func, const char *fmt, va_list ap);
00082 
00083 #define ast_verbose_ap(fmt, ap)  __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, ap)
00084 
00085 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
00086 
00087 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
00088 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
00089 
00090 void ast_console_puts(const char *string);
00091 
00092 /*!
00093  * \brief log the string to the console, and all attached
00094  * console clients
00095  * \version 1.6.1 added level parameter
00096  */
00097 void ast_console_puts_mutable(const char *string, int level);
00098 void ast_console_toggle_mute(int fd, int silent);
00099 
00100 /*!
00101  * \brief enables or disables logging of a specified level to the console
00102  * fd specifies the index of the console receiving the level change
00103  * level specifies the index of the logging level being toggled
00104  * state indicates whether logging will be on or off (0 for off, 1 for on)
00105  */
00106 void ast_console_toggle_loglevel(int fd, int level, int state);
00107 
00108 /* Note: The AST_LOG_* macros below are the same as
00109  * the LOG_* macros and are intended to eventually replace
00110  * the LOG_* macros to avoid name collisions with the syslog(3)
00111  * log levels. However, please do NOT remove
00112  * the LOG_* macros from the source since these may be still
00113  * needed for third-party modules
00114  */
00115 
00116 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
00117 
00118 #ifdef LOG_DEBUG
00119 #undef LOG_DEBUG
00120 #endif
00121 #define __LOG_DEBUG    0
00122 #define LOG_DEBUG      __LOG_DEBUG, _A_
00123 
00124 #ifdef AST_LOG_DEBUG
00125 #undef AST_LOG_DEBUG
00126 #endif
00127 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
00128 
00129 #ifdef LOG_NOTICE
00130 #undef LOG_NOTICE
00131 #endif
00132 #define __LOG_NOTICE   2
00133 #define LOG_NOTICE     __LOG_NOTICE, _A_
00134 
00135 #ifdef AST_LOG_NOTICE
00136 #undef AST_LOG_NOTICE
00137 #endif
00138 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
00139 
00140 #ifdef LOG_WARNING
00141 #undef LOG_WARNING
00142 #endif
00143 #define __LOG_WARNING  3
00144 #define LOG_WARNING    __LOG_WARNING, _A_
00145 
00146 #ifdef AST_LOG_WARNING
00147 #undef AST_LOG_WARNING
00148 #endif
00149 #define AST_LOG_WARNING    __LOG_WARNING, _A_
00150 
00151 #ifdef LOG_ERROR
00152 #undef LOG_ERROR
00153 #endif
00154 #define __LOG_ERROR    4
00155 #define LOG_ERROR      __LOG_ERROR, _A_
00156 
00157 #ifdef AST_LOG_ERROR
00158 #undef AST_LOG_ERROR
00159 #endif
00160 #define AST_LOG_ERROR      __LOG_ERROR, _A_
00161 
00162 #ifdef LOG_VERBOSE
00163 #undef LOG_VERBOSE
00164 #endif
00165 #define __LOG_VERBOSE  5
00166 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
00167 
00168 #ifdef AST_LOG_VERBOSE
00169 #undef AST_LOG_VERBOSE
00170 #endif
00171 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
00172 
00173 #ifdef LOG_DTMF
00174 #undef LOG_DTMF
00175 #endif
00176 #define __LOG_DTMF  6
00177 #define LOG_DTMF    __LOG_DTMF, _A_
00178 
00179 #ifdef AST_LOG_DTMF
00180 #undef AST_LOG_DTMF
00181 #endif
00182 #define AST_LOG_DTMF    __LOG_DTMF, _A_
00183 
00184 #define NUMLOGLEVELS 32
00185 
00186 /*!
00187  * \brief Get the debug level for a module
00188  * \param module the name of module
00189  * \return the debug level
00190  */
00191 unsigned int ast_debug_get_by_module(const char *module);
00192 
00193 /*!
00194  * \brief Get the verbose level for a module
00195  * \param module the name of module
00196  * \return the verbose level
00197  */
00198 unsigned int ast_verbose_get_by_module(const char *module);
00199 
00200 /*!
00201  * \brief Register a new logger level
00202  * \param name The name of the level to be registered
00203  * \retval -1 if an error occurs
00204  * \retval non-zero level to be used with ast_log for sending messages to this level
00205  * \since 1.8
00206  */
00207 int ast_logger_register_level(const char *name);
00208 
00209 /*!
00210  * \brief Unregister a previously registered logger level
00211  * \param name The name of the level to be unregistered
00212  * \return nothing
00213  * \since 1.8
00214  */
00215 void ast_logger_unregister_level(const char *name);
00216 
00217 /*!
00218  * \brief Send a log message to a dynamically registered log level
00219  * \param level The log level to send the message to
00220  *
00221  * Like ast_log, the log message may include printf-style formats, and
00222  * the data for these must be provided as additional parameters after
00223  * the log message.
00224  *
00225  * \return nothing
00226  * \since 1.8
00227  */
00228 
00229 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
00230 
00231 /*!
00232  * \brief Log a DEBUG message
00233  * \param level The minimum value of option_debug for this message
00234  *        to get logged
00235  */
00236 #define ast_debug(level, ...) do {       \
00237    if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
00238       ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
00239 } while (0)
00240 
00241 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_module && ast_verbose_get_by_module(AST_MODULE) >= (level)))
00242 
00243 #define ast_verb(level, ...) do { \
00244    if (VERBOSITY_ATLEAST((level)) ) { \
00245       if (level >= 4) \
00246          ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
00247       else if (level == 3) \
00248          ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
00249       else if (level == 2) \
00250          ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
00251       else if (level == 1) \
00252          ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
00253       else \
00254          ast_verbose(__VA_ARGS__); \
00255    } \
00256 } while (0)
00257 
00258 #ifndef _LOGGER_BACKTRACE_H
00259 #define _LOGGER_BACKTRACE_H
00260 #ifdef HAVE_BKTR
00261 #define AST_MAX_BT_FRAMES 32
00262 /* \brief
00263  *
00264  * A structure to hold backtrace information. This structure provides an easy means to
00265  * store backtrace information or pass backtraces to other functions.
00266  */
00267 struct ast_bt {
00268    /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
00269    void *addresses[AST_MAX_BT_FRAMES];
00270    /*! The number of stack frames in the backtrace */
00271    int num_frames;
00272    /*! Tells if the ast_bt structure was dynamically allocated */
00273    unsigned int alloced:1;
00274 };
00275 
00276 /* \brief
00277  * Allocates memory for an ast_bt and stores addresses and symbols.
00278  *
00279  * \return Returns NULL on failure, or the allocated ast_bt on success
00280  * \since 1.6.1
00281  */
00282 struct ast_bt *ast_bt_create(void);
00283 
00284 /* \brief
00285  * Fill an allocated ast_bt with addresses
00286  *
00287  * \retval 0 Success
00288  * \retval -1 Failure
00289  * \since 1.6.1
00290  */
00291 int ast_bt_get_addresses(struct ast_bt *bt);
00292 
00293 /* \brief
00294  *
00295  * Free dynamically allocated portions of an ast_bt
00296  *
00297  * \retval NULL.
00298  * \since 1.6.1
00299  */
00300 void *ast_bt_destroy(struct ast_bt *bt);
00301 
00302 /* \brief Retrieve symbols for a set of backtrace addresses
00303  *
00304  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
00305  * \param num_frames Number of addresses in the addresses list
00306  * \retval NULL Unable to allocate memory
00307  * \return List of strings
00308  * \since 1.6.2.16
00309  */
00310 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
00311 
00312 #endif /* HAVE_BKTR */
00313 #endif /* _LOGGER_BACKTRACE_H */
00314 
00315 #if defined(__cplusplus) || defined(c_plusplus)
00316 }
00317 #endif
00318 
00319 #endif /* _ASTERISK_LOGGER_H */

Generated on Mon Oct 8 12:39:03 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7