include/yaz/log.h

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