Update source headers for 2008. Omit CVS ID keyword subst.
[yaz-moved-to-github.git] / 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