log.h revision 291767 
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 * Get the thread id from logging system.  Set after log_init is
102 * initialised, or log_thread_set for newly created threads.
103 * This initialisation happens in unbound as a daemon, in daemon
104 * startup code, when that spawns threads.
105 * @return thread number, from 0 and up.  Before initialised, returns 0.
106 */
107int log_thread_get(void);
108
109/**
110 * Set identity to print, default is 'unbound'.
111 * @param id: string to print. Name of executable.
112 */
113void log_ident_set(const char* id);
114
115/**
116 * Set the time value to print in log entries.
117 * @param t: the point is copied and used to find the time.
118 * 	if NULL, time(2) is used.
119 */
120void log_set_time(time_t* t);
121
122/**
123 * Set if the time value is printed ascii or decimal in log entries.
124 * @param use_asc: if true, ascii is printed, otherwise decimal.
125 *	If the conversion fails or you have no time functions,
126 *	decimal is printed.
127 */
128void log_set_time_asc(int use_asc);
129
130/**
131 * Log informational message.
132 * Pass printf formatted arguments. No trailing newline is needed.
133 * @param format: printf-style format string. Arguments follow.
134 */
135void log_info(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
136
137/**
138 * Log error message.
139 * Pass printf formatted arguments. No trailing newline is needed.
140 * @param format: printf-style format string. Arguments follow.
141 */
142void log_err(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
143
144/**
145 * Log warning message.
146 * Pass printf formatted arguments. No trailing newline is needed.
147 * @param format: printf-style format string. Arguments follow.
148 */
149void log_warn(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
150
151/**
152 * Log a hex-string to the log. Can be any length.
153 * performs mallocs to do so, slow. But debug useful.
154 * @param msg: string desc to accompany the hexdump.
155 * @param data: data to dump in hex format.
156 * @param length: length of data.
157 */
158void log_hex(const char* msg, void* data, size_t length);
159
160/**
161 * Easy alternative for log_hex, takes a sldns_buffer.
162 * @param level: verbosity level for this message, compared to global
163 *	verbosity setting.
164 * @param msg: string desc to print
165 * @param buf: the buffer.
166 */
167void log_buf(enum verbosity_value level, const char* msg, struct sldns_buffer* buf);
168
169/**
170 * Log fatal error message, and exit the current process.
171 * Pass printf formatted arguments. No trailing newline is needed.
172 * @param format: printf-style format string. Arguments follow.
173 */
174void fatal_exit(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
175
176/**
177 * va_list argument version of log_info.
178 * @param pri: priority type, for example 5 (INFO).
179 * @param type: string to designate type of message (info, error).
180 * @param format: the printf style format to print. no newline.
181 * @param args: arguments for format string.
182 */
183void log_vmsg(int pri, const char* type, const char* format, va_list args);
184
185/**
186 * an assertion that is thrown to the logfile.
187 */
188#ifdef UNBOUND_DEBUG
189#  define log_assert(x) \
190	do { if(!(x)) \
191		fatal_exit("%s:%d: %s: assertion %s failed", \
192			__FILE__, __LINE__, __func__, #x); \
193	} while(0);
194#else
195#  define log_assert(x) /*nothing*/
196#endif
197
198#ifdef USE_WINSOCK
199/**
200 * Convert WSA error into string.
201 * @param err: from WSAGetLastError()
202 * @return: string.
203 */
204char* wsa_strerror(DWORD err);
205#endif /* USE_WINSOCK */
206
207#endif /* UTIL_LOG_H */
208