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 default identity to print, default is 'unbound'. 117 * @param id: string to print. Name of executable. 118 */ 119 void log_ident_set_default(const char* id); 120 121 /** 122 * Revert identity to print, back to the recorded default value. 123 */ 124 void log_ident_revert_to_default(void); 125 126 /** 127 * Set identity to print if there is an identity, otherwise 128 * set the default. 129 * @param identity: the identity to set. 130 */ 131 void log_ident_set_or_default(const char* identity); 132 133 /** 134 * Set if the time value is printed ascii or decimal in log entries. 135 * @param use_asc: if true, ascii is printed, otherwise decimal. 136 * If the conversion fails or you have no time functions, 137 * decimal is printed. 138 */ 139 void log_set_time_asc(int use_asc); 140 141 /** 142 * Set if the time value is printed in ISO8601 format. 143 * @param use_iso: if true, ascii timestamps are formatted in iso format. 144 */ 145 void log_set_time_iso(int use_iso); 146 147 /** get log lock */ 148 void* log_get_lock(void); 149 150 /** 151 * Log informational message. 152 * Pass printf formatted arguments. No trailing newline is needed. 153 * @param format: printf-style format string. Arguments follow. 154 */ 155 void log_info(const char* format, ...) ATTR_FORMAT(printf, 1, 2); 156 157 /** 158 * Log error message. 159 * Pass printf formatted arguments. No trailing newline is needed. 160 * @param format: printf-style format string. Arguments follow. 161 */ 162 void log_err(const char* format, ...) ATTR_FORMAT(printf, 1, 2); 163 164 /** 165 * Log warning message. 166 * Pass printf formatted arguments. No trailing newline is needed. 167 * @param format: printf-style format string. Arguments follow. 168 */ 169 void log_warn(const char* format, ...) ATTR_FORMAT(printf, 1, 2); 170 171 /** 172 * Log a hex-string to the log. Can be any length. 173 * performs mallocs to do so, slow. But debug useful. 174 * @param msg: string desc to accompany the hexdump. 175 * @param data: data to dump in hex format. 176 * @param length: length of data. 177 */ 178 void log_hex(const char* msg, void* data, size_t length); 179 180 /** 181 * Log query. 182 * Pass printf formatted arguments. No trailing newline is needed. 183 * @param format: printf-style format string. Arguments follow. 184 */ 185 void log_query(const char* format, ...) ATTR_FORMAT(printf, 1, 2); 186 187 /** 188 * Log reply. 189 * Pass printf formatted arguments. No trailing newline is needed. 190 * @param format: printf-style format string. Arguments follow. 191 */ 192 void log_reply(const char* format, ...) ATTR_FORMAT(printf, 1, 2); 193 194 /** 195 * Easy alternative for log_hex, takes a sldns_buffer. 196 * @param level: verbosity level for this message, compared to global 197 * verbosity setting. 198 * @param msg: string desc to print 199 * @param buf: the buffer. 200 */ 201 void log_buf(enum verbosity_value level, const char* msg, struct sldns_buffer* buf); 202 203 /** 204 * Log fatal error message, and exit the current process. 205 * Pass printf formatted arguments. No trailing newline is needed. 206 * @param format: printf-style format string. Arguments follow. 207 */ 208 void fatal_exit(const char* format, ...) ATTR_FORMAT(printf, 1, 2) ATTR_NORETURN; 209 210 /** 211 * va_list argument version of log_info. 212 * @param pri: priority type, for example 5 (INFO). 213 * @param type: string to designate type of message (info, error). 214 * @param format: the printf style format to print. no newline. 215 * @param args: arguments for format string. 216 */ 217 void log_vmsg(int pri, const char* type, const char* format, va_list args); 218 219 /** 220 * an assertion that is thrown to the logfile. 221 */ 222 #ifdef UNBOUND_DEBUG 223 #ifdef __clang_analyzer__ 224 /* clang analyzer needs to know that log_assert is an assertion, otherwise 225 * it could complain about the nullptr the assert is guarding against. */ 226 #define log_assert(x) assert(x) 227 #else 228 # define log_assert(x) \ 229 do { if(!(x)) \ 230 fatal_exit("%s:%d: %s: assertion %s failed", \ 231 __FILE__, __LINE__, __func__, #x); \ 232 } while(0); 233 #endif 234 #else 235 # define log_assert(x) /*nothing*/ 236 #endif 237 238 #ifdef USE_WINSOCK 239 /** 240 * Convert WSA error into string. 241 * @param err: from WSAGetLastError() 242 * @return: string. 243 */ 244 char* wsa_strerror(DWORD err); 245 #endif /* USE_WINSOCK */ 246 247 #endif /* UTIL_LOG_H */ 248