xref: /freebsd/contrib/unbound/util/log.h (revision a25896ca1270e25b657ceaa8d47d5699515f5c25)
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
44 struct sldns_buffer;
45 
46 /**
47  * verbosity value:
48  */
49 enum 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 */
65 extern 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  */
74 void 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  */
83 void 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  */
90 void 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  */
98 void 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  */
107 int log_thread_get(void);
108 
109 /**
110  * Set identity to print, default is 'unbound'.
111  * @param id: string to print. Name of executable.
112  */
113 void 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  */
120 void 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  */
128 void log_set_time_asc(int use_asc);
129 
130 /** get log lock */
131 void* log_get_lock(void);
132 
133 /**
134  * Log informational message.
135  * Pass printf formatted arguments. No trailing newline is needed.
136  * @param format: printf-style format string. Arguments follow.
137  */
138 void log_info(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
139 
140 /**
141  * Log error message.
142  * Pass printf formatted arguments. No trailing newline is needed.
143  * @param format: printf-style format string. Arguments follow.
144  */
145 void log_err(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
146 
147 /**
148  * Log warning message.
149  * Pass printf formatted arguments. No trailing newline is needed.
150  * @param format: printf-style format string. Arguments follow.
151  */
152 void log_warn(const char* format, ...) ATTR_FORMAT(printf, 1, 2);
153 
154 /**
155  * Log a hex-string to the log. Can be any length.
156  * performs mallocs to do so, slow. But debug useful.
157  * @param msg: string desc to accompany the hexdump.
158  * @param data: data to dump in hex format.
159  * @param length: length of data.
160  */
161 void log_hex(const char* msg, void* data, size_t length);
162 
163 /**
164  * Easy alternative for log_hex, takes a sldns_buffer.
165  * @param level: verbosity level for this message, compared to global
166  *	verbosity setting.
167  * @param msg: string desc to print
168  * @param buf: the buffer.
169  */
170 void log_buf(enum verbosity_value level, const char* msg, struct sldns_buffer* buf);
171 
172 /**
173  * Log fatal error message, and exit the current process.
174  * Pass printf formatted arguments. No trailing newline is needed.
175  * @param format: printf-style format string. Arguments follow.
176  */
177 void fatal_exit(const char* format, ...) ATTR_FORMAT(printf, 1, 2) ATTR_NORETURN;
178 
179 /**
180  * va_list argument version of log_info.
181  * @param pri: priority type, for example 5 (INFO).
182  * @param type: string to designate type of message (info, error).
183  * @param format: the printf style format to print. no newline.
184  * @param args: arguments for format string.
185  */
186 void log_vmsg(int pri, const char* type, const char* format, va_list args);
187 
188 /**
189  * an assertion that is thrown to the logfile.
190  */
191 #ifdef UNBOUND_DEBUG
192 #ifdef __clang_analyzer__
193 /* clang analyzer needs to know that log_assert is an assertion, otherwise
194  * it could complain about the nullptr the assert is guarding against. */
195 #define log_assert(x) assert(x)
196 #else
197 #  define log_assert(x) \
198 	do { if(!(x)) \
199 		fatal_exit("%s:%d: %s: assertion %s failed", \
200 			__FILE__, __LINE__, __func__, #x); \
201 	} while(0);
202 #endif
203 #else
204 #  define log_assert(x) /*nothing*/
205 #endif
206 
207 #ifdef USE_WINSOCK
208 /**
209  * Convert WSA error into string.
210  * @param err: from WSAGetLastError()
211  * @return: string.
212  */
213 char* wsa_strerror(DWORD err);
214 #endif /* USE_WINSOCK */
215 
216 #endif /* UTIL_LOG_H */
217