Fri Jul 24 00:40:59 2009

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  * \since 1.6.1
00102  */
00103 void ast_console_toggle_loglevel(int fd, int level, int state);
00104 
00105 /* Note: The AST_LOG_* macros below are the same as
00106  * the LOG_* macros and are intended to eventually replace
00107  * the LOG_* macros to avoid name collisions as has been
00108  * seen in app_voicemail. However, please do NOT remove
00109  * the LOG_* macros from the source since these may be still
00110  * needed for third-party modules
00111  */
00112 
00113 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
00114 
00115 #ifdef LOG_DEBUG
00116 #undef LOG_DEBUG
00117 #endif
00118 #define __LOG_DEBUG    0
00119 #define LOG_DEBUG      __LOG_DEBUG, _A_
00120 
00121 #ifdef AST_LOG_DEBUG
00122 #undef AST_LOG_DEBUG
00123 #endif
00124 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
00125 
00126 #ifdef LOG_EVENT
00127 #undef LOG_EVENT
00128 #endif
00129 #define __LOG_EVENT    1
00130 #define LOG_EVENT      __LOG_EVENT, _A_
00131 
00132 #ifdef AST_LOG_EVENT
00133 #undef AST_LOG_EVENT
00134 #endif
00135 #define AST_LOG_EVENT      __LOG_EVENT, _A_
00136 
00137 #ifdef LOG_NOTICE
00138 #undef LOG_NOTICE
00139 #endif
00140 #define __LOG_NOTICE   2
00141 #define LOG_NOTICE     __LOG_NOTICE, _A_
00142 
00143 #ifdef AST_LOG_NOTICE
00144 #undef AST_LOG_NOTICE
00145 #endif
00146 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
00147 
00148 #ifdef LOG_WARNING
00149 #undef LOG_WARNING
00150 #endif
00151 #define __LOG_WARNING  3
00152 #define LOG_WARNING    __LOG_WARNING, _A_
00153 
00154 #ifdef AST_LOG_WARNING
00155 #undef AST_LOG_WARNING
00156 #endif
00157 #define AST_LOG_WARNING    __LOG_WARNING, _A_
00158 
00159 #ifdef LOG_ERROR
00160 #undef LOG_ERROR
00161 #endif
00162 #define __LOG_ERROR    4
00163 #define LOG_ERROR      __LOG_ERROR, _A_
00164 
00165 #ifdef AST_LOG_ERROR
00166 #undef AST_LOG_ERROR
00167 #endif
00168 #define AST_LOG_ERROR      __LOG_ERROR, _A_
00169 
00170 #ifdef LOG_VERBOSE
00171 #undef LOG_VERBOSE
00172 #endif
00173 #define __LOG_VERBOSE  5
00174 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
00175 
00176 #ifdef AST_LOG_VERBOSE
00177 #undef AST_LOG_VERBOSE
00178 #endif
00179 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
00180 
00181 #ifdef LOG_DTMF
00182 #undef LOG_DTMF
00183 #endif
00184 #define __LOG_DTMF  6
00185 #define LOG_DTMF    __LOG_DTMF, _A_
00186 
00187 #ifdef AST_LOG_DTMF
00188 #undef AST_LOG_DTMF
00189 #endif
00190 #define AST_LOG_DTMF    __LOG_DTMF, _A_
00191 
00192 #define NUMLOGLEVELS 6
00193 
00194 /*!
00195  * \brief Get the debug level for a file
00196  * \param file the filename
00197  * \return the debug level
00198  */
00199 unsigned int ast_debug_get_by_file(const char *file);
00200 
00201 /*!
00202  * \brief Get the debug level for a file
00203  * \param file the filename
00204  * \return the debug level
00205  */
00206 unsigned int ast_verbose_get_by_file(const char *file);
00207 
00208 /*!
00209  * \brief Log a DEBUG message
00210  * \param level The minimum value of option_debug for this message
00211  *        to get logged
00212  */
00213 #define ast_debug(level, ...) do {       \
00214    if (option_debug >= (level) || (ast_opt_dbg_file && ast_debug_get_by_file(__FILE__) >= (level)) ) \
00215       ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
00216 } while (0)
00217 
00218 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_file && ast_verbose_get_by_file(__FILE__) >= (level)))
00219 
00220 #define ast_verb(level, ...) do { \
00221    if (VERBOSITY_ATLEAST((level)) ) { \
00222       if (level >= 4) \
00223          ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
00224       else if (level == 3) \
00225          ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
00226       else if (level == 2) \
00227          ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
00228       else if (level == 1) \
00229          ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
00230       else \
00231          ast_verbose(__VA_ARGS__); \
00232    } \
00233 } while (0)
00234 
00235 #ifndef _LOGGER_BACKTRACE_H
00236 #define _LOGGER_BACKTRACE_H
00237 #ifdef HAVE_BKTR
00238 #define AST_MAX_BT_FRAMES 32
00239 /* \brief
00240  *
00241  * A structure to hold backtrace information. This structure provides an easy means to
00242  * store backtrace information or pass backtraces to other functions.
00243  */
00244 struct ast_bt {
00245    /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
00246    void *addresses[AST_MAX_BT_FRAMES];
00247    /*! The number of stack frames in the backtrace */
00248    int num_frames;
00249    /*! Tells if the ast_bt structure was dynamically allocated */
00250    unsigned int alloced:1;
00251 };
00252 
00253 /* \brief
00254  * Allocates memory for an ast_bt and stores addresses and symbols.
00255  *
00256  * \return Returns NULL on failure, or the allocated ast_bt on success
00257  * \since 1.6.1
00258  */
00259 struct ast_bt *ast_bt_create(void);
00260 
00261 /* \brief
00262  * Fill an allocated ast_bt with addresses
00263  *
00264  * \retval 0 Success
00265  * \retval -1 Failure
00266  * \since 1.6.1
00267  */
00268 int ast_bt_get_addresses(struct ast_bt *bt);
00269 
00270 /* \brief
00271  *
00272  * Free dynamically allocated portions of an ast_bt
00273  *
00274  * \retval NULL.
00275  * \since 1.6.1
00276  */
00277 void *ast_bt_destroy(struct ast_bt *bt);
00278 
00279 #endif /* HAVE_BKTR */
00280 #endif /* _LOGGER_BACKTRACE_H */
00281 
00282 #if defined(__cplusplus) || defined(c_plusplus)
00283 }
00284 #endif
00285 
00286 #endif /* _ASTERISK_LOGGER_H */

Generated on Fri Jul 24 00:40:59 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7