include/yaz/log.h

   1 /*
   2  * Copyright (C) 1995-2006, Index Data ApS
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and
   5  * its documentation, in whole or in part, for any purpose, is hereby granted,
   6  * provided that:
   7  *
   8  * 1. This copyright and permission notice appear in all copies of the
   9  * software and its documentation. Notices of copyright or attribution
  10  * which appear at the beginning of any file must remain unchanged.
  11  *
  12  * 2. The name of Index Data or the individual authors may not be used to
  13  * endorse or promote products derived from this software without specific
  14  * prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  18  * WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  19  * IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
  20  * INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
  21  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
  22  * NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  23  * LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  24  * OF THIS SOFTWARE.
  25  *
  26  * $Id: log.h,v 1.38 2006-07-06 13:10:29 heikki Exp $
  27  */
  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 #if YAZ_USE_NEW_LOG
 200
 201 #else
 202
 203 #include <yaz/xmalloc.h>
 204
 205 /** The old LOG_ bit names are here for compatibility only. They may
 206     conflict with bits defined in syslog.h, or other places. 'LOG'
 207     really is not such a good name. YLOG must be more unique
 208 */
 209
 210 /** \brief old log level */
 211 #define LOG_FATAL  YLOG_FATAL
 212 /** \brief old log level */
 213 #define LOG_DEBUG  YLOG_DEBUG
 214 /** \brief old log level */
 215 #define LOG_WARN   YLOG_WARN
 216 /** \brief old log level */
 217 #define LOG_LOG    YLOG_LOG
 218 /** \brief old log level */
 219 #define LOG_ERRNO  YLOG_ERRNO
 220 /** \brief old log level */
 221 #define LOG_FILE   0x00000020
 222 /** \brief old log level */
 223 #define LOG_APP    YLOG_APP
 224 /** \brief old log level */
 225 #define LOG_MALLOC YLOG_MALLOC
 226 /** \brief old log level */
 227 #define LOG_NOTIME YLOG_NOTIME
 228 /** \brief old log level */
 229 #define LOG_APP2   YLOG_APP2
 230 /** \brief old log level */
 231 #define LOG_APP3   YLOG_APP3
 232 /** \brief old log level */
 233 #define LOG_FLUSH  YLOG_FLUSH
 234 /** \brief old log level */
 235 #define LOG_ALL    YLOG_ALL
 236 /** \brief old log level */
 237 #define LOG_DEFAULT_LEVEL YLOG_DEFAULT_LEVEL
 238
 239 /** \brief logf is deprecated, as it conflicts with a math function */
 240 #define logf yaz_log
 241
 242 #endif /* if YAZ_USE_NEW_LOG */
 243
 244 YAZ_END_CDECL
 245
 246 #endif
 247 /*
 248  * Local variables:
 249  * c-basic-offset: 4
 250  * indent-tabs-mode: nil
 251  * End:
 252  * vim: shiftwidth=4 tabstop=8 expandtab
 253  */
 254