include/yaz/log.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) 1995-2009 Index Data.
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of Index Data nor the names of its contributors
  13  *       may be used to endorse or promote products derived from this
  14  *       software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /**
  29  * \file log.h
  30  * \brief Logging utility
  31  */
  32
  33 #ifndef YAZ_LOG_H
  34 #define YAZ_LOG_H
  35
  36 #include <stdio.h>
  37 #include <yaz/yconfig.h>
  38
  39 YAZ_BEGIN_CDECL
  40
  41 /** \brief log level: fatal */
  42 #define YLOG_FATAL  0x00000001
  43 /** \brief log level: debugging */
  44 #define YLOG_DEBUG  0x00000002
  45 /** \brief log level: warning */
  46 #define YLOG_WARN   0x00000004
  47 /** \brief log level: log (regular) */
  48 #define YLOG_LOG    0x00000008
  49 /** \brief log level: append system error message */
  50 #define YLOG_ERRNO  0x00000010
  51 /** \brief log level: application */
  52 #define YLOG_APP    0x00000040
  53 /** \brief log level: malloc debug */
  54 #define YLOG_MALLOC 0x00000080
  55 /** \brief log level: do not output date and time */
  56 #define YLOG_NOTIME 0x00000100
  57 /** \brief log level: application 2 */
  58 #define YLOG_APP2   0x00000200
  59 /** \brief log level: application 3 */
  60 #define YLOG_APP3   0x00000400
  61 /** \brief log level: flush */
  62 #define YLOG_FLUSH  0x00000800
  63 /** \brief dynamic log level start */
  64 #define YLOG_LOGLVL 0x00001000 /* log when modules query log levels */
  65                               /* this has to be a hard-coded bit, not to loop*/
  66
  67 #define YLOG_ALL   (0xffff&~YLOG_MALLOC&~YLOG_NOTIME)
  68
  69 /** \brief default log level */
  70 #define YLOG_DEFAULT_LEVEL \
  71     (YLOG_FATAL | YLOG_ERRNO | YLOG_LOG | YLOG_WARN | YLOG_FLUSH)
  72 /* not having flush here confuses Solaris users, who won't see any logs until
  73  * (and if) the program exits normally */
  74
  75 /** \brief last bit for regular log bits . Rest are dynamic */
  76 #define YLOG_LAST_BIT YLOG_LOGLVL
  77
  78 /** \brief sets level, prefix and filename for logging
  79     \param level log level
  80     \param prefix log message prefix
  81     \param fname filename
  82 */
  83 YAZ_EXPORT void yaz_log_init(int level, const char *prefix, const char *fname);
  84
  85 /** \brief sets log to a file
  86     \param fname filename
  87 */
  88 YAZ_EXPORT void yaz_log_init_file(const char *fname);
  89
  90 /** \brief sets log level
  91     \param level (combination of YLOG_..)
  92 */
  93 YAZ_EXPORT void yaz_log_init_level(int level);
  94
  95 /** \brief sets log message prefix
  96     \param prefix log message prefix
  97 */
  98 YAZ_EXPORT void yaz_log_init_prefix(const char *prefix);
  99
 100 /** \brief sets second log message prefix
 101     \param prefix log message prefix
 102 */
 103 YAZ_EXPORT void yaz_log_init_prefix2(const char *prefix);
 104
 105 /** \brief sets time format for log mesages
 106     \param fmt format (strftime)
 107
 108     Sets the format of the timestamp. See man 3 strftime.
 109     Calling with "old" sets to the old format "11:55:06-02/11"
 110     Calling with NULL or "" sets to the new format "20041102-115719"
 111     If not called at all, the old format is used, for backward compatibility
 112 */
 113 YAZ_EXPORT void yaz_log_time_format(const char *fmt);
 114
 115 /** \brief sets limit in bytes for size for log file
 116     \param mx size in bytes
 117
 118     Sets the max size for a log file. Zero means no limit.
 119     Negative means built-in limit (1GB)
 120 */
 121 YAZ_EXPORT void yaz_log_init_max_size(int mx);
 122
 123 /** \brief Writes log message
 124     \param level log level mask
 125     \param fmt format string ala printf
 126
 127     Writes an entry in the log. Defaults to stderr if not initialized or
 128     to a file with yaz_log_init_file(). The level must match the level set
 129     via yaz_log_init_level(), optionally defined via yaz_log_mask_str().
 130 */
 131 YAZ_EXPORT void yaz_log(int level, const char *fmt, ...)
 132 #ifdef __GNUC__
 133         __attribute__ ((format (printf, 2, 3)))
 134 #endif
 135         ;
 136
 137 /** \brief converts log level string to log level (integer)
 138     \param str log level string
 139     \return log level mask
 140
 141     yaz_log_mask_str() converts a comma-separated list of log levels to a
 142     bit mask. Starts from default level, and adds bits as specified,
 143     unless 'none' is specified, which clears the list. If a name matches
 144     the name of a YLOG_BIT above, that one is set. Otherwise a new value is
 145     picked, and given to that name, to be found with yaz_log_module_level()
 146 */
 147 YAZ_EXPORT int yaz_log_mask_str(const char *str);
 148
 149 /** \brief converts log level string to log level with "start" level
 150     \param str log level string
 151     \param level initialing log level
 152     \return log level mask
 153
 154     yaz_log_mask_str_x() is like yaz_log_mask_str(), but with a given start
 155     value
 156 */
 157 YAZ_EXPORT int yaz_log_mask_str_x(const char *str, int level);
 158
 159
 160 /** \brief returns level for module
 161     \param name module name
 162
 163     yaz_log_module_level() returns a log level mask corresponding to the
 164     module name. If that had been specified on the -v arguments (that is
 165     passed to yaz_log_mask_str()), then a non-zero mask is returned. If
 166     not, we get a zero. This can later be used in yaz_log for the level
 167     argument
 168  */
 169 YAZ_EXPORT int yaz_log_module_level(const char *name);
 170
 171 /** \brief returns FILE handle for log or NULL if no file is in use
 172     \retval FILE FILE handle in use
 173     \retval NULL log is currently not written to a file
 174 */
 175 YAZ_EXPORT FILE *yaz_log_file(void);
 176
 177 /** \brief sets custom log handler
 178     \param func custom log handler
 179     \param info custom pointer to be passed to func handler
 180
 181     Allows log output to be captured to something else.. The
 182     func parameter takes a log level, a message + custom pointer
 183 */
 184 YAZ_EXPORT void yaz_log_set_handler(void (*func)(int, const char *,
 185                                                  void *), void *info);
 186
 187 YAZ_EXPORT void yaz_log_reopen(void);
 188
 189 /** \brief Truncate the log file */
 190 YAZ_EXPORT void yaz_log_trunc(void);
 191
 192 YAZ_EXPORT void log_event_start(void (*func)(int level, const char *msg,
 193                                              void *info), void *info);
 194
 195 YAZ_EXPORT void log_event_end(void (*func)(int level, const char *msg,
 196                                            void *info), void *info);
 197
 198
 199 /** \brief Makes Libxml2/Libxslt log errors via yaz_log
 200     \param prefix prefix to use for log messages (may be 0)
 201     \param log_level log level to use for messages
 202 */
 203 YAZ_EXPORT void yaz_log_xml_errors(const char *prefix, int log_level);
 204
 205 /* by default, do not enable the old LOG_-defines */
 206 #ifndef YAZ_USE_NEW_LOG
 207 #define YAZ_USE_NEW_LOG 1
 208 #endif
 209
 210 #if YAZ_USE_NEW_LOG
 211
 212 #else
 213
 214 #include <yaz/xmalloc.h>
 215
 216 /** The old LOG_ bit names are here for compatibility only. They may
 217     conflict with bits defined in syslog.h, or other places. 'LOG'
 218     really is not such a good name. YLOG must be more unique
 219 */
 220
 221 /** \brief old log level */
 222 #define LOG_FATAL  YLOG_FATAL
 223 /** \brief old log level */
 224 #define LOG_DEBUG  YLOG_DEBUG
 225 /** \brief old log level */
 226 #define LOG_WARN   YLOG_WARN
 227 /** \brief old log level */
 228 #define LOG_LOG    YLOG_LOG
 229 /** \brief old log level */
 230 #define LOG_ERRNO  YLOG_ERRNO
 231 /** \brief old log level */
 232 #define LOG_FILE   0x00000020
 233 /** \brief old log level */
 234 #define LOG_APP    YLOG_APP
 235 /** \brief old log level */
 236 #define LOG_MALLOC YLOG_MALLOC
 237 /** \brief old log level */
 238 #define LOG_NOTIME YLOG_NOTIME
 239 /** \brief old log level */
 240 #define LOG_APP2   YLOG_APP2
 241 /** \brief old log level */
 242 #define LOG_APP3   YLOG_APP3
 243 /** \brief old log level */
 244 #define LOG_FLUSH  YLOG_FLUSH
 245 /** \brief old log level */
 246 #define LOG_ALL    YLOG_ALL
 247 /** \brief old log level */
 248 #define LOG_DEFAULT_LEVEL YLOG_DEFAULT_LEVEL
 249
 250 /** \brief logf is deprecated, as it conflicts with a math function */
 251 #define logf yaz_log
 252
 253 #endif /* if !YAZ_USE_NEW_LOG  */
 254
 255 YAZ_END_CDECL
 256
 257 #endif
 258 /*
 259  * Local variables:
 260  * c-basic-offset: 4
 261  * indent-tabs-mode: nil
 262  * End:
 263  * vim: shiftwidth=4 tabstop=8 expandtab
 264  */
 265