Tor  0.4.7.0-alpha-dev
log.h
Go to the documentation of this file.
1 /* Copyright (c) 2001, Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * \file log.h
9  *
10  * \brief Headers for log.c
11  **/
12 
13 #ifndef TOR_TORLOG_H
14 #define TOR_TORLOG_H
15 
16 #include <stdarg.h>
17 #include "lib/cc/torint.h"
18 #include "lib/cc/compat_compiler.h"
19 #include "lib/defs/logging_types.h"
21 
22 #ifdef HAVE_SYSLOG_H
23 #include <syslog.h>
24 #define LOG_WARN LOG_WARNING
25 #if LOG_DEBUG < LOG_ERR
26 #ifndef COCCI
27 #error "Your syslog.h thinks high numbers are more important. " \
28  "We aren't prepared to deal with that."
29 #endif
30 #endif /* LOG_DEBUG < LOG_ERR */
31 #else /* !defined(HAVE_SYSLOG_H) */
32 /* Note: Syslog's logging code refers to priorities, with 0 being the most
33  * important. Thus, all our comparisons needed to be reversed when we added
34  * syslog support.
35  *
36  * The upshot of this is that comments about log levels may be messed up: for
37  * "maximum severity" read "most severe" and "numerically *lowest* severity".
38  */
39 
40 /** Debug-level severity: for hyper-verbose messages of no interest to
41  * anybody but developers. */
42 #define LOG_DEBUG 7
43 /** Info-level severity: for messages that appear frequently during normal
44  * operation. */
45 #define LOG_INFO 6
46 /** Notice-level severity: for messages that appear infrequently
47  * during normal operation; that the user will probably care about;
48  * and that are not errors.
49  */
50 #define LOG_NOTICE 5
51 /** Warn-level severity: for messages that only appear when something has gone
52  * wrong. */
53 #define LOG_WARN 4
54 /** Error-level severity: for messages that only appear when something has gone
55  * very wrong, and the Tor process can no longer proceed. */
56 #define LOG_ERR 3
57 #endif /* defined(HAVE_SYSLOG_H) */
58 
59 /* Logging domains */
60 
61 /** Catch-all for miscellaneous events and fatal errors. */
62 #define LD_GENERAL (UINT64_C(1)<<0)
63 /** The cryptography subsystem. */
64 #define LD_CRYPTO (UINT64_C(1)<<1)
65 /** Networking. */
66 #define LD_NET (UINT64_C(1)<<2)
67 /** Parsing and acting on our configuration. */
68 #define LD_CONFIG (UINT64_C(1)<<3)
69 /** Reading and writing from the filesystem. */
70 #define LD_FS (UINT64_C(1)<<4)
71 /** Other servers' (non)compliance with the Tor protocol. */
72 #define LD_PROTOCOL (UINT64_C(1)<<5)
73 /** Memory management. */
74 #define LD_MM (UINT64_C(1)<<6)
75 /** HTTP implementation. */
76 #define LD_HTTP (UINT64_C(1)<<7)
77 /** Application (socks) requests. */
78 #define LD_APP (UINT64_C(1)<<8)
79 /** Communication via the controller protocol. */
80 #define LD_CONTROL (UINT64_C(1)<<9)
81 /** Building, using, and managing circuits. */
82 #define LD_CIRC (UINT64_C(1)<<10)
83 /** Hidden services. */
84 #define LD_REND (UINT64_C(1)<<11)
85 /** Internal errors in this Tor process. */
86 #define LD_BUG (UINT64_C(1)<<12)
87 /** Learning and using information about Tor servers. */
88 #define LD_DIR (UINT64_C(1)<<13)
89 /** Learning and using information about Tor servers. */
90 #define LD_DIRSERV (UINT64_C(1)<<14)
91 /** Onion routing protocol. */
92 #define LD_OR (UINT64_C(1)<<15)
93 /** Generic edge-connection functionality. */
94 #define LD_EDGE (UINT64_C(1)<<16)
95 #define LD_EXIT LD_EDGE
96 /** Bandwidth accounting. */
97 #define LD_ACCT (UINT64_C(1)<<17)
98 /** Router history */
99 #define LD_HIST (UINT64_C(1)<<18)
100 /** OR handshaking */
101 #define LD_HANDSHAKE (UINT64_C(1)<<19)
102 /** Heartbeat messages */
103 #define LD_HEARTBEAT (UINT64_C(1)<<20)
104 /** Abstract channel_t code */
105 #define LD_CHANNEL (UINT64_C(1)<<21)
106 /** Scheduler */
107 #define LD_SCHED (UINT64_C(1)<<22)
108 /** Guard nodes */
109 #define LD_GUARD (UINT64_C(1)<<23)
110 /** Generation and application of consensus diffs. */
111 #define LD_CONSDIFF (UINT64_C(1)<<24)
112 /** Denial of Service mitigation. */
113 #define LD_DOS (UINT64_C(1)<<25)
114 /** Processes */
115 #define LD_PROCESS (UINT64_C(1)<<26)
116 /** Pluggable Transports. */
117 #define LD_PT (UINT64_C(1)<<27)
118 /** Bootstrap tracker. */
119 #define LD_BTRACK (UINT64_C(1)<<28)
120 /** Message-passing backend. */
121 #define LD_MESG (UINT64_C(1)<<29)
122 
123 /** The number of log domains. */
124 #define N_LOGGING_DOMAINS 30
125 /** The highest log domain */
126 #define HIGHEST_RESERVED_LD_DOMAIN_ (UINT64_C(1)<<(N_LOGGING_DOMAINS - 1))
127 /** All log domains. */
128 #define LD_ALL_DOMAINS ((~(UINT64_C(0)))>>(64 - N_LOGGING_DOMAINS))
129 
130 /** The number of log flags. */
131 #define N_LOGGING_FLAGS 3
132 /** First bit that is reserved in log_domain_mask_t for non-domain flags. */
133 #define LOWEST_RESERVED_LD_FLAG_ (UINT64_C(1)<<(64 - N_LOGGING_FLAGS))
134 /** All log flags. */
135 #define LD_ALL_FLAGS ((~(UINT64_C(0)))<<(64 - N_LOGGING_FLAGS))
136 
137 #ifdef TOR_UNIT_TESTS
138 /** This log message should not be intercepted by mock_saving_logv */
139 #define LD_NO_MOCK (UINT64_C(1)<<61)
140 #endif
141 
142 /** This log message is not safe to send to a callback-based logger
143  * immediately. Used as a flag, not a log domain. */
144 #define LD_NOCB (UINT64_C(1)<<62)
145 /** This log message should not include a function name, even if it otherwise
146  * would. Used as a flag, not a log domain. */
147 #define LD_NOFUNCNAME (UINT64_C(1)<<63)
148 
149 /** Configures which severities are logged for each logging domain for a given
150  * log target. */
151 typedef struct log_severity_list_t {
152  /** For each log severity, a bitmask of which domains a given logger is
153  * logging. */
156 
157 /** Callback type used for add_callback_log. */
158 typedef void (*log_callback)(int severity, log_domain_mask_t domain,
159  const char *msg);
160 
161 void init_logging(int disable_startup_queue);
162 int parse_log_level(const char *level);
163 const char *log_level_to_string(int level);
164 int parse_log_severity_config(const char **cfg,
165  log_severity_list_t *severity_out);
166 void set_log_severity_config(int minSeverity, int maxSeverity,
167  log_severity_list_t *severity_out);
168 void add_stream_log(const log_severity_list_t *severity,
169  const char *name, int fd);
170 MOCK_DECL(int, add_file_log,(const log_severity_list_t *severity,
171  const char *filename,
172  int fd));
173 
174 #ifdef HAVE_SYSLOG_H
175 int add_syslog_log(const log_severity_list_t *severity,
176  const char* syslog_identity_tag);
177 #endif // HAVE_SYSLOG_H.
178 int add_callback_log(const log_severity_list_t *severity, log_callback cb);
179 typedef void (*pending_callback_callback)(void);
180 void logs_set_pending_callback_callback(pending_callback_callback cb);
181 void logs_set_domain_logging(int enabled);
182 int get_min_log_level(void);
183 void switch_logs_debug(void);
184 void logs_free_all(void);
185 void logs_flush_sigsafe(void);
186 void add_default_log(int min_severity);
187 void close_temp_logs(void);
188 void rollback_log_changes(void);
189 void mark_logs_temp(void);
190 void change_callback_log_severity(int loglevelMin, int loglevelMax,
191  log_callback cb);
192 void flush_pending_log_callbacks(void);
194 void log_set_application_name(const char *name);
195 MOCK_DECL(void, set_log_time_granularity,(int granularity_msec));
196 void truncate_logs(void);
197 
198 void tor_log(int severity, log_domain_mask_t domain, const char *format, ...)
199  CHECK_PRINTF(3,4);
200 
202 
203 struct smartlist_t;
204 void tor_log_get_logfile_names(struct smartlist_t *out);
205 
206 extern int log_global_min_severity_;
207 
208 #ifdef TOR_COVERAGE
209 /* For coverage builds, we try to avoid our log_debug optimization, since it
210  * can have weird effects on internal macro coverage. */
211 #define debug_logging_enabled() (1)
212 #else
213 static inline bool debug_logging_enabled(void);
214 /**
215  * Return true iff debug logging is enabled for at least one domain.
216  */
217 static inline bool debug_logging_enabled(void)
218 {
219  return PREDICT_UNLIKELY(log_global_min_severity_ == LOG_DEBUG);
220 }
221 #endif /* defined(TOR_COVERAGE) */
222 
223 void log_fn_(int severity, log_domain_mask_t domain,
224  const char *funcname, const char *format, ...)
225  CHECK_PRINTF(4,5);
226 struct ratelim_t;
227 void log_fn_ratelim_(struct ratelim_t *ratelim, int severity,
228  log_domain_mask_t domain, const char *funcname,
229  const char *format, ...)
230  CHECK_PRINTF(5,6);
231 
232 int log_message_is_interesting(int severity, log_domain_mask_t domain);
233 void tor_log_string(int severity, log_domain_mask_t domain,
234  const char *function, const char *string);
235 
236 #if defined(__GNUC__) && __GNUC__ <= 3
237 
238 /* These are the GCC varidaic macros, so that older versions of GCC don't
239  * break. */
240 
241 /** Log a message at level <b>severity</b>, using a pretty-printed version
242  * of the current function name. */
243 #define log_fn(severity, domain, args...) \
244  log_fn_(severity, domain, __FUNCTION__, args)
245 /** As log_fn, but use <b>ratelim</b> (an instance of ratelim_t) to control
246  * the frequency at which messages can appear.
247  */
248 #define log_fn_ratelim(ratelim, severity, domain, args...) \
249  log_fn_ratelim_(ratelim, severity, domain, __FUNCTION__, args)
250 #define log_debug(domain, args...) \
251  STMT_BEGIN \
252  if (debug_logging_enabled()) \
253  log_fn_(LOG_DEBUG, domain, __FUNCTION__, args); \
254  STMT_END
255 #define log_info(domain, args...) \
256  log_fn_(LOG_INFO, domain, __FUNCTION__, args)
257 #define log_notice(domain, args...) \
258  log_fn_(LOG_NOTICE, domain, __FUNCTION__, args)
259 #define log_warn(domain, args...) \
260  log_fn_(LOG_WARN, domain, __FUNCTION__, args)
261 #define log_err(domain, args...) \
262  log_fn_(LOG_ERR, domain, __FUNCTION__, args)
263 
264 #else /* !(defined(__GNUC__) && __GNUC__ <= 3) */
265 
266 /* Here are the c99 variadic macros, to work with non-GCC compilers */
267 
268 #define log_debug(domain, args, ...) \
269  STMT_BEGIN \
270  if (debug_logging_enabled()) \
271  log_fn_(LOG_DEBUG, domain, __FUNCTION__, args, ##__VA_ARGS__); \
272  STMT_END
273 #define log_info(domain, args,...) \
274  log_fn_(LOG_INFO, domain, __FUNCTION__, args, ##__VA_ARGS__)
275 #define log_notice(domain, args,...) \
276  log_fn_(LOG_NOTICE, domain, __FUNCTION__, args, ##__VA_ARGS__)
277 #define log_warn(domain, args,...) \
278  log_fn_(LOG_WARN, domain, __FUNCTION__, args, ##__VA_ARGS__)
279 #define log_err(domain, args,...) \
280  log_fn_(LOG_ERR, domain, __FUNCTION__, args, ##__VA_ARGS__)
281 /** Log a message at level <b>severity</b>, using a pretty-printed version
282  * of the current function name. */
283 #define log_fn(severity, domain, args,...) \
284  log_fn_(severity, domain, __FUNCTION__, args, ##__VA_ARGS__)
285 /** As log_fn, but use <b>ratelim</b> (an instance of ratelim_t) to control
286  * the frequency at which messages can appear.
287  */
288 #define log_fn_ratelim(ratelim, severity, domain, args,...) \
289  log_fn_ratelim_(ratelim, severity, domain, __FUNCTION__, \
290  args, ##__VA_ARGS__)
291 #endif /* defined(__GNUC__) && __GNUC__ <= 3 */
292 
293 /** This defines log levels that are linked in the Rust log module, rather
294  * than re-defining these in both Rust and C.
295  *
296  * C_RUST_COUPLED src/rust/tor_log LogSeverity, LogDomain
297  */
298 extern const int LOG_WARN_;
299 extern const int LOG_NOTICE_;
300 extern const log_domain_mask_t LD_NET_;
301 extern const log_domain_mask_t LD_GENERAL_;
302 
303 #ifdef LOG_PRIVATE
304 MOCK_DECL(STATIC void, logv, (int severity, log_domain_mask_t domain,
305  const char *funcname, const char *suffix, const char *format,
306  va_list ap) CHECK_PRINTF(5,0));
308  const log_severity_list_t *severity, const char *name, int fd));
309 #endif /* defined(LOG_PRIVATE) */
310 
311 #if defined(LOG_PRIVATE) || defined(TOR_UNIT_TESTS)
312 /** Given a severity, yields an index into log_severity_list_t.masks to use
313  * for that severity. */
314 #define SEVERITY_MASK_IDX(sev) ((sev) - LOG_ERR)
315 #endif
316 
317 #endif /* !defined(TOR_TORLOG_H) */
Utility macros to handle different features and behavior in different compilers.
const char * name
Definition: config.c:2434
STATIC void add_stream_log_impl(const log_severity_list_t *severity, const char *name, int fd)
Definition: log.c:885
STATIC void logv(int severity, log_domain_mask_t domain, const char *funcname, const char *suffix, const char *format, va_list ap)
Definition: log.c:535
const int LOG_WARN_
Definition: log.c:63
int add_file_log(const log_severity_list_t *severity, const char *filename, int fd)
Definition: log.c:1148
void tor_log(int severity, log_domain_mask_t domain, const char *format,...)
Definition: log.c:590
void init_logging(int disable_startup_queue)
Definition: log.c:911
void set_log_severity_config(int minSeverity, int maxSeverity, log_severity_list_t *severity_out)
Definition: log.c:868
void flush_log_messages_from_startup(void)
Definition: log.c:1058
void log_fn_(int severity, log_domain_mask_t domain, const char *funcname, const char *format,...)
Definition: log.c:705
void change_callback_log_severity(int loglevelMin, int loglevelMax, log_callback cb)
Definition: log.c:997
void mark_logs_temp(void)
Definition: log.c:1131
void logs_free_all(void)
Definition: log.c:745
void logs_flush_sigsafe(void)
Definition: log.c:791
void truncate_logs(void)
Definition: log.c:1456
void rollback_log_changes(void)
Definition: log.c:1119
void logs_set_pending_callback_callback(pending_callback_callback cb)
Definition: log.c:967
int add_callback_log(const log_severity_list_t *severity, log_callback cb)
Definition: log.c:977
void switch_logs_debug(void)
Definition: log.c:1441
void tor_log_string(int severity, log_domain_mask_t domain, const char *function, const char *string)
Definition: log.c:235
int get_min_log_level(void)
Definition: log.c:1426
void log_set_application_name(const char *name)
Definition: log.c:211
#define LOG_DEBUG
Definition: log.h:42
const char * log_level_to_string(int level)
Definition: log.c:1231
static bool debug_logging_enabled(void)
Definition: log.h:217
void set_log_time_granularity(int granularity_msec)
Definition: log.c:247
void flush_pending_log_callbacks(void)
Definition: log.c:1016
int log_message_is_interesting(int severity, log_domain_mask_t domain)
Definition: log.c:222
void(* log_callback)(int severity, log_domain_mask_t domain, const char *msg)
Definition: log.h:158
int log_global_min_severity_
Definition: log.c:187
void tor_log_update_sigsafe_err_fds(void)
Definition: log.c:625
int parse_log_severity_config(const char **cfg, log_severity_list_t *severity_out)
Definition: log.c:1322
void add_stream_log(const log_severity_list_t *severity, const char *name, int fd)
Definition: log.c:902
#define LOG_ERR
Definition: log.h:56
void add_default_log(int min_severity)
Definition: log.c:944
void tor_log_get_logfile_names(struct smartlist_t *out)
Definition: log.c:683
int parse_log_level(const char *level)
Definition: log.c:1214
void logs_set_domain_logging(int enabled)
Definition: log.c:934
void close_temp_logs(void)
Definition: log.c:1095
Global definition for types used by logging systems.
uint64_t log_domain_mask_t
Definition: logging_types.h:21
log_domain_mask_t masks[LOG_DEBUG-LOG_ERR+1]
Definition: log.h:154
Macros to implement mocking and selective exposure for the test code.
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Integer definitions used throughout Tor.