log.h revision 269257 
1/*
2 * util/log.h - logging service
3 *
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
5 *
6 * This software is open source.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 *
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 */
35
36/**
37 * \file
38 *
39 * This file contains logging functions.
40 */
41
42#ifndef UTIL_LOG_H
43#define UTIL_LOG_H
44struct sldns_buffer;
45
46/**
47 * verbosity value:
48 */
49enum verbosity_value {
50 /** 0 - no verbose messages */
51	NO_VERBOSE = 0,
52 /** 1 - operational information */
53 	VERB_OPS,
54 /** 2 - detailed information */
55 	VERB_DETAIL,
56 /** 3 - query level information */
57 	VERB_QUERY,
58 /** 4 - algorithm level information */
59 	VERB_ALGO,
60 /** 5 - querier client information */
61	VERB_CLIENT
62};
63
64/** The global verbosity setting */
65extern enum verbosity_value verbosity;
66
67/**
68 * log a verbose message, pass the level for this message.
69 * It has printf formatted arguments. No trailing newline is needed.
70 * @param level: verbosity level for this message, compared to global
71 *	verbosity setting.
72 * @param format: printf-style format string. Arguments follow.
73 */
74void verbose(enum verbosity_value level,
75	const char* format, ...) ATTR_FORMAT(printf, 2, 3);
76
77/**
78 * call this to initialize logging services.
79 * @param filename: if NULL stderr is used.
80 * @param use_syslog: set to true to ignore filename and use syslog(3).
81 * @param chrootdir: to which directory we have been chrooted, if any.
82 */
83void log_init(const char* filename, int use_syslog, const char* chrootdir);
84
85/**
86 * Set logging to go to the specified file *.
87 * This setting does not affect the use_syslog setting.
88 * @param f: to that file, or pass NULL to disable logging.
89 */
90void log_file(FILE *f);
91
92/**
93 * Init a thread (will print this number for the thread log entries).
94 * Must be called from the thread itself. If not called 0 is printed.
95 * @param num: number to print for this thread. Owned by caller, must
96 *	continue to exist.
97 */
98void log_thread_set(int* num);
99
100/**
101 * Set identity to print, default is 'unbound'.
102 * @param id: string to print. Name of executable.
103 */
104void log_ident_set(const char* id);
105
106/**
107 * Set the time value to print in log entries.
108 * @param t: the point is copied and used to find the time.
109 * 	if NULL, time(2) is used.
110 */
111void log_set_time(time_t* t);
112
113/**
114 * Set if the time value is printed ascii or decimal in log entries.
115 * @param use_asc: if true, ascii is printed, otherwise decimal.
116 *	If the conversion fails or you have no time functions,
117 *	decimal is printed.
118 */
119void log_set_time_asc(int use_asc);
120
121/**
122 * Log informational message.
123 * Pass printf formatted arguments. No trailing newline is needed.
124 * @param format: printf-style format string. Arguments follow.
125 */
126void log_info(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
127
128/**
129 * Log error message.
130 * Pass printf formatted arguments. No trailing newline is needed.
131 * @param format: printf-style format string. Arguments follow.
132 */
133void log_err(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
134
135/**
136 * Log warning message.
137 * Pass printf formatted arguments. No trailing newline is needed.
138 * @param format: printf-style format string. Arguments follow.
139 */
140void log_warn(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
141
142/**
143 * Log a hex-string to the log. Can be any length.
144 * performs mallocs to do so, slow. But debug useful.
145 * @param msg: string desc to accompany the hexdump.
146 * @param data: data to dump in hex format.
147 * @param length: length of data.
148 */
149void log_hex(const char* msg, void* data, size_t length);
150
151/**
152 * Easy alternative for log_hex, takes a sldns_buffer.
153 * @param level: verbosity level for this message, compared to global
154 *	verbosity setting.
155 * @param msg: string desc to print
156 * @param buf: the buffer.
157 */
158void log_buf(enum verbosity_value level, const char* msg, struct sldns_buffer* buf);
159
160/**
161 * Log fatal error message, and exit the current process.
162 * Pass printf formatted arguments. No trailing newline is needed.
163 * @param format: printf-style format string. Arguments follow.
164 */
165void fatal_exit(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
166
167/**
168 * va_list argument version of log_info.
169 * @param pri: priority type, for example 5 (INFO).
170 * @param type: string to designate type of message (info, error).
171 * @param format: the printf style format to print. no newline.
172 * @param args: arguments for format string.
173 */
174void log_vmsg(int pri, const char* type, const char* format, va_list args);
175
176/**
177 * an assertion that is thrown to the logfile.
178 */
179#ifdef UNBOUND_DEBUG
180#  define log_assert(x) \
181	do { if(!(x)) \
182		fatal_exit("%s:%d: %s: assertion %s failed", \
183			__FILE__, __LINE__, __func__, #x); \
184	} while(0);
185#else
186#  define log_assert(x) /*nothing*/
187#endif
188
189#ifdef USE_WINSOCK
190/**
191 * Convert WSA error into string.
192 * @param err: from WSAGetLastError()
193 * @return: string.
194 */
195char* wsa_strerror(DWORD err);
196#endif /* USE_WINSOCK */
197
198#endif /* UTIL_LOG_H */
199