Data Structures | Macros | Typedefs | Functions | Variables
log.h File Reference
#include <stdarg.h>
#include "lib/cc/torint.h"
#include "lib/cc/compat_compiler.h"
#include "lib/testsupport/testsupport.h"

Go to the source code of this file.

Data Structures

struct  log_severity_list_t


#define LOG_DEBUG   7
#define LOG_INFO   6
#define LOG_NOTICE   5
#define LOG_WARN   4
#define LOG_ERR   3
#define LD_GENERAL   (1u<<0)
#define LD_CRYPTO   (1u<<1)
#define LD_NET   (1u<<2)
#define LD_CONFIG   (1u<<3)
#define LD_FS   (1u<<4)
#define LD_PROTOCOL   (1u<<5)
#define LD_MM   (1u<<6)
#define LD_HTTP   (1u<<7)
#define LD_APP   (1u<<8)
#define LD_CONTROL   (1u<<9)
#define LD_CIRC   (1u<<10)
#define LD_REND   (1u<<11)
#define LD_BUG   (1u<<12)
#define LD_DIR   (1u<<13)
#define LD_DIRSERV   (1u<<14)
#define LD_OR   (1u<<15)
#define LD_EDGE   (1u<<16)
#define LD_EXIT   LD_EDGE
#define LD_ACCT   (1u<<17)
#define LD_HIST   (1u<<18)
#define LD_HANDSHAKE   (1u<<19)
#define LD_HEARTBEAT   (1u<<20)
#define LD_CHANNEL   (1u<<21)
#define LD_SCHED   (1u<<22)
#define LD_GUARD   (1u<<23)
#define LD_CONSDIFF   (1u<<24)
#define LD_DOS   (1u<<25)
#define LD_PROCESS   (1u<<26)
#define LD_PT   (1u<<27)
#define LD_BTRACK   (1u<<28)
#define LD_MESG   (1u<<29)
#define N_LOGGING_DOMAINS   30
#define LD_NOCB   (1u<<31)
#define LD_NOFUNCNAME   (1u<<30)
#define log_debug(domain, args, ...)
#define log_info(domain, args, ...)   log_fn_(LOG_INFO, domain, __FUNCTION__, args, ##__VA_ARGS__)
#define log_notice(domain, args, ...)   log_fn_(LOG_NOTICE, domain, __FUNCTION__, args, ##__VA_ARGS__)
#define log_warn(domain, args, ...)   log_fn_(LOG_WARN, domain, __FUNCTION__, args, ##__VA_ARGS__)
#define log_err(domain, args, ...)   log_fn_(LOG_ERR, domain, __FUNCTION__, args, ##__VA_ARGS__)
#define log_fn(severity, domain, args, ...)   log_fn_(severity, domain, __FUNCTION__, args, ##__VA_ARGS__)
#define log_fn_ratelim(ratelim, severity, domain, args, ...)


typedef uint32_t log_domain_mask_t
typedef struct log_severity_list_t log_severity_list_t
typedef void(* log_callback) (int severity, uint32_t domain, const char *msg)
typedef void(* pending_callback_callback) (void)


void init_logging (int disable_startup_queue)
int parse_log_level (const char *level)
const char * log_level_to_string (int level)
int parse_log_severity_config (const char **cfg, log_severity_list_t *severity_out)
void set_log_severity_config (int minSeverity, int maxSeverity, log_severity_list_t *severity_out)
void add_stream_log (const log_severity_list_t *severity, const char *name, int fd)
int add_file_log (const log_severity_list_t *severity, const char *filename, int fd)
int add_callback_log (const log_severity_list_t *severity, log_callback cb)
void logs_set_pending_callback_callback (pending_callback_callback cb)
void logs_set_domain_logging (int enabled)
int get_min_log_level (void)
void switch_logs_debug (void)
void logs_free_all (void)
void add_temp_log (int min_severity)
void close_temp_logs (void)
void rollback_log_changes (void)
void mark_logs_temp (void)
void change_callback_log_severity (int loglevelMin, int loglevelMax, log_callback cb)
void flush_pending_log_callbacks (void)
void flush_log_messages_from_startup (void)
void log_set_application_name (const char *name)
void set_log_time_granularity (int granularity_msec)
void truncate_logs (void)
void tor_log (int severity, log_domain_mask_t domain, const char *format,...) CHECK_PRINTF(3
void void tor_log_update_sigsafe_err_fds (void)
void tor_log_get_logfile_names (struct smartlist_t *out)
static bool debug_logging_enabled (void)
void log_fn_ (int severity, log_domain_mask_t domain, const char *funcname, const char *format,...) CHECK_PRINTF(4
void log_fn_ratelim_ (struct ratelim_t *ratelim, int severity, log_domain_mask_t domain, const char *funcname, const char *format,...) CHECK_PRINTF(5
void int log_message_is_interesting (int severity, log_domain_mask_t domain)
void tor_log_string (int severity, log_domain_mask_t domain, const char *function, const char *string)


int log_global_min_severity_
const int LOG_WARN_
const int LOG_NOTICE_
const log_domain_mask_t LD_NET_
const log_domain_mask_t LD_GENERAL_

Detailed Description

Headers for log.c.

Definition in file log.h.

Macro Definition Documentation


#define LD_ACCT   (1u<<17)

Bandwidth accounting.

Definition at line 94 of file log.h.


#define LD_APP   (1u<<8)

Application (socks) requests.

Definition at line 75 of file log.h.


#define LD_BTRACK   (1u<<28)

Bootstrap tracker.

Definition at line 116 of file log.h.


#define LD_BUG   (1u<<12)

Internal errors in this Tor process.

Definition at line 83 of file log.h.


#define LD_CHANNEL   (1u<<21)

Abstract channel_t code

Definition at line 102 of file log.h.


#define LD_CIRC   (1u<<10)

Building, using, and managing circuits.

Definition at line 79 of file log.h.


#define LD_CONFIG   (1u<<3)

Parsing and acting on our configuration.

Definition at line 65 of file log.h.


#define LD_CONSDIFF   (1u<<24)

Generation and application of consensus diffs.

Definition at line 108 of file log.h.


#define LD_CONTROL   (1u<<9)

Communication via the controller protocol.

Definition at line 77 of file log.h.


#define LD_CRYPTO   (1u<<1)

The cryptography subsystem.

Definition at line 61 of file log.h.


#define LD_DIR   (1u<<13)

Learning and using information about Tor servers.

Definition at line 85 of file log.h.


#define LD_DIRSERV   (1u<<14)

Learning and using information about Tor servers.

Definition at line 87 of file log.h.


#define LD_DOS   (1u<<25)

Denial of Service mitigation.

Definition at line 110 of file log.h.


#define LD_EDGE   (1u<<16)

Generic edge-connection functionality.

Definition at line 91 of file log.h.


#define LD_FS   (1u<<4)

Reading and writing from the filesystem.

Definition at line 67 of file log.h.


#define LD_GENERAL   (1u<<0)

Catch-all for miscellaneous events and fatal errors.

Definition at line 59 of file log.h.


#define LD_GUARD   (1u<<23)

Guard nodes

Definition at line 106 of file log.h.


#define LD_HANDSHAKE   (1u<<19)

OR handshaking

Definition at line 98 of file log.h.


#define LD_HEARTBEAT   (1u<<20)

Heartbeat messages

Definition at line 100 of file log.h.


#define LD_HIST   (1u<<18)

Router history

Definition at line 96 of file log.h.


#define LD_HTTP   (1u<<7)

HTTP implementation.

Definition at line 73 of file log.h.


#define LD_MESG   (1u<<29)

Message-passing backend.

Definition at line 118 of file log.h.


#define LD_MM   (1u<<6)

Memory management.

Definition at line 71 of file log.h.


#define LD_NET   (1u<<2)


Definition at line 63 of file log.h.


#define LD_NOCB   (1u<<31)

This log message is not safe to send to a callback-based logger immediately. Used as a flag, not a log domain.

Definition at line 123 of file log.h.


#define LD_NOFUNCNAME   (1u<<30)

This log message should not include a function name, even if it otherwise would. Used as a flag, not a log domain.

Definition at line 126 of file log.h.


#define LD_OR   (1u<<15)

Onion routing protocol.

Definition at line 89 of file log.h.


#define LD_PROCESS   (1u<<26)


Definition at line 112 of file log.h.


#define LD_PROTOCOL   (1u<<5)

Other servers' (non)compliance with the Tor protocol.

Definition at line 69 of file log.h.


#define LD_PT   (1u<<27)

Pluggable Transports.

Definition at line 114 of file log.h.


#define LD_REND   (1u<<11)

Hidden services.

Definition at line 81 of file log.h.


#define LD_SCHED   (1u<<22)


Definition at line 104 of file log.h.


#define LOG_DEBUG   7

Debug-level severity: for hyper-verbose messages of no interest to anybody but developers.

Definition at line 39 of file log.h.

◆ log_debug

#define log_debug (   domain,
log_fn_(LOG_DEBUG, domain, __FUNCTION__, args, ##__VA_ARGS__); \
#define LOG_DEBUG
Definition: log.h:39
static bool debug_logging_enabled(void)
Definition: log.h:201

Definition at line 251 of file log.h.


#define LOG_ERR   3

Error-level severity: for messages that only appear when something has gone very wrong, and the Tor process can no longer proceed.

Definition at line 53 of file log.h.

◆ log_fn

#define log_fn (   severity,
)    log_fn_(severity, domain, __FUNCTION__, args, ##__VA_ARGS__)

Log a message at level severity, using a pretty-printed version of the current function name.

Definition at line 266 of file log.h.

◆ log_fn_ratelim

#define log_fn_ratelim (   ratelim,
log_fn_ratelim_(ratelim, severity, domain, __FUNCTION__, \
args, ##__VA_ARGS__)

As log_fn, but use ratelim (an instance of ratelim_t) to control the frequency at which messages can appear.

Definition at line 271 of file log.h.


#define LOG_INFO   6

Info-level severity: for messages that appear frequently during normal operation.

Definition at line 42 of file log.h.


#define LOG_NOTICE   5

Notice-level severity: for messages that appear infrequently during normal operation; that the user will probably care about; and that are not errors.

Definition at line 47 of file log.h.


#define LOG_WARN   4

Warn-level severity: for messages that only appear when something has gone wrong.

Definition at line 50 of file log.h.

Typedef Documentation

◆ log_callback

typedef void(* log_callback) (int severity, uint32_t domain, const char *msg)

Callback type used for add_callback_log.

Definition at line 145 of file log.h.

◆ log_domain_mask_t

typedef uint32_t log_domain_mask_t

Mask of zero or more log domains, OR'd together.

Definition at line 134 of file log.h.

◆ log_severity_list_t

Configures which severities are logged for each logging domain for a given log target.

Function Documentation

◆ add_callback_log()

int add_callback_log ( const log_severity_list_t severity,
log_callback  cb 

Add a log handler to send messages in severity to the function cb.

Definition at line 970 of file log.c.

◆ add_file_log()

int add_file_log ( const log_severity_list_t severity,
const char *  filename,
int  fd 

Add a log handler to send messages to filename via fd. If opening the logfile failed, -1 is returned and errno is set appropriately (by open(2)). Takes ownership of fd.

Definition at line 1140 of file log.c.

References add_stream_log_impl(), delete_log(), get_min_log_level(), LOCK_LOGS, log_global_min_severity_, log_tor_version(), logfiles, logfile_t::needs_close, tor_fd_seekend(), and UNLOCK_LOGS.

Referenced by open_and_add_file_log().

◆ add_stream_log()

void add_stream_log ( const log_severity_list_t severity,
const char *  name,
int  fd 

Add a log handler named name to send all messages in severity to fd. Steals a reference to severity; the caller must not use it after calling this function.

Definition at line 893 of file log.c.

◆ add_temp_log()

void add_temp_log ( int  min_severity)

Add a log handler to receive messages during startup (before the real logs are initialized).

Definition at line 936 of file log.c.

◆ change_callback_log_severity()

void change_callback_log_severity ( int  loglevelMin,
int  loglevelMax,
log_callback  cb 

Adjust the configured severity of any logs whose callback function is cb.

Definition at line 990 of file log.c.

References logfile_t::callback, get_min_log_level(), LOCK_LOGS, log_global_min_severity_, logfiles, logfile_t::next, set_log_severity_config(), logfile_t::severities, and UNLOCK_LOGS.

Referenced by control_adjust_event_log_severity().

◆ close_temp_logs()

void close_temp_logs ( void  )

Close any log handlers added by add_temp_log() or marked by mark_logs_temp().

Definition at line 1089 of file log.c.

References close_log(), LOCK_LOGS, logfiles, and logfile_t::next.

Referenced by rollback_log_changes().

◆ debug_logging_enabled()

static bool debug_logging_enabled ( void  )

Return true iff debug logging is enabled for at least one domain.

Definition at line 201 of file log.h.

Referenced by dispatch_send_msg_unchecked(), and dispatcher_run_msg_cbs().

◆ flush_log_messages_from_startup()

void flush_log_messages_from_startup ( void  )

Flush all the messages we stored from startup while waiting for log initialization.

Definition at line 1051 of file log.c.

References logfile_t::fd, LOCK_LOGS, logfile_deliver(), logfile_wants_message(), logfiles, logfile_t::next, pending_startup_messages, pending_startup_messages_len, queue_startup_messages, and SMARTLIST_FOREACH_BEGIN.

◆ flush_pending_log_callbacks()

void flush_pending_log_callbacks ( void  )

If there are any log messages that were generated with LD_NOCB waiting to be sent to callback-based loggers, send them now.

Definition at line 1009 of file log.c.

References LOCK_LOGS, and pending_cb_messages.

Referenced by queued_events_flush_all().

◆ get_min_log_level()

int get_min_log_level ( void  )

Return the least severe log level that any current log is interested in.

Definition at line 1450 of file log.c.

References LOG_DEBUG, LOG_ERR, logfiles, log_severity_list_t::masks, logfile_t::next, logfile_t::severities, and SEVERITY_MASK_IDX.

Referenced by add_file_log(), change_callback_log_severity(), options_act_reversible(), and switch_logs_debug().

◆ init_logging()

void init_logging ( int  disable_startup_queue)

Initialize the global logging facility

Definition at line 902 of file log.c.

References log_mutex, log_mutex_initialized, pending_cb_messages, pending_startup_messages, pretty_fn_has_parens, queue_startup_messages, and tor_mutex_init().

◆ log_level_to_string()

const char* log_level_to_string ( int  level)

Return the string equivalent of a given log level.

Definition at line 1258 of file log.c.

References sev_to_string().

◆ log_message_is_interesting()

void int log_message_is_interesting ( int  severity,
log_domain_mask_t  domain 

Return true if some of the running logs might be interested in a log message of the given severity in the given domains. If this function returns true, the log message might be ignored anyway, but if it returns false, it is definitely_ safe not to log the message.

Definition at line 258 of file log.c.

References log_global_min_severity_.

◆ log_set_application_name()

void log_set_application_name ( const char *  name)

Set the "application name" for the logs to name: we'll use this name in the message we write when starting up, and at the start of each new log.

Tor uses this string to write the version number to the log file.

Definition at line 247 of file log.c.

Referenced by tor_init().

◆ logs_free_all()

void logs_free_all ( void  )

Close all open log files, and free other static memory.

Definition at line 775 of file log.c.

References close_log(), LOCK_LOGS, logfiles, logfile_t::next, pending_cb_cb, pending_cb_messages, pending_startup_messages, and UNLOCK_LOGS.

◆ logs_set_domain_logging()

void logs_set_domain_logging ( int  enabled)

Set whether we report logging domains as a part of our log messages.

Definition at line 925 of file log.c.

References LOCK_LOGS, log_domains_are_logged, and UNLOCK_LOGS.

◆ logs_set_pending_callback_callback()

void logs_set_pending_callback_callback ( pending_callback_callback  cb)

Register "cb" as the callback to call when there are new pending log callbacks to be flushed with flush_pending_log_callbacks().

Note that this callback, if present, can be invoked from any thread.

This callback must not log.

It is intentional that this function contains the name "callback" twice: it sets a "callback" to be called on the condition that there is a "pending callback".

Definition at line 960 of file log.c.

◆ mark_logs_temp()

void mark_logs_temp ( void  )

Configure all log handles to be closed by close_temp_logs().

Definition at line 1125 of file log.c.

References logfile_t::is_temporary, LOCK_LOGS, logfiles, logfile_t::next, and UNLOCK_LOGS.

◆ parse_log_level()

int parse_log_level ( const char *  level)

If level is a valid log severity, return the corresponding numeric value. Otherwise, return -1.

Definition at line 1241 of file log.c.


◆ parse_log_severity_config()

int parse_log_severity_config ( const char **  cfg_ptr,
log_severity_list_t severity_out 

Parse a log severity pattern in *cfg_ptr. Advance cfg_ptr after the end of the severityPattern. Set the value of severity_out to the parsed pattern. Return 0 on success, -1 on failure.

The syntax for a SeverityPattern is:

  SeverityPattern = *(DomainSeverity SP)* DomainSeverity
  DomainSeverity = (DomainList SP)? SeverityRange
  SeverityRange = MinSeverity ("-" MaxSeverity )?
  DomainList = "[" (SP? DomainSpec SP? ",") SP? DomainSpec "]"
  DomainSpec = "*" | Domain | "~" Domain

A missing MaxSeverity defaults to ERR. Severities and domains are case-insensitive. "~" indicates negation for a domain; negation happens last inside a DomainList. Only one SeverityRange without a DomainList is allowed per line.

Definition at line 1345 of file log.c.

References eat_whitespace().

◆ rollback_log_changes()

void rollback_log_changes ( void  )

Make all currently temporary logs (set to be closed by close_temp_logs) live again, and close all non-temporary logs.

Definition at line 1113 of file log.c.

References close_temp_logs(), logfile_t::is_temporary, LOCK_LOGS, logfiles, logfile_t::next, and UNLOCK_LOGS.

◆ set_log_severity_config()

void set_log_severity_config ( int  loglevelMin,
int  loglevelMax,
log_severity_list_t severity_out 

Adjust a log severity configuration in severity_out to contain every domain between loglevelMin and loglevelMax, inclusive.

Definition at line 859 of file log.c.

Referenced by change_callback_log_severity().

◆ set_log_time_granularity()

void set_log_time_granularity ( int  granularity_msec)

Define log time granularity for all logs to be granularity_msec milliseconds.

Definition at line 283 of file log.c.

References log_time_granularity, and tor_log_sigsafe_err_set_granularity().

◆ switch_logs_debug()

void switch_logs_debug ( void  )

Switch all logs to output at most verbose level.

Definition at line 1465 of file log.c.

References get_min_log_level(), LOCK_LOGS, LOG_DEBUG, LOG_ERR, log_global_min_severity_, logfiles, log_severity_list_t::masks, logfile_t::next, logfile_t::severities, SEVERITY_MASK_IDX, and UNLOCK_LOGS.

◆ tor_log_get_logfile_names()

void tor_log_get_logfile_names ( smartlist_t out)

Add to out a copy of every currently configured log file name. Used to enable access to these filenames with the sandbox code.

Definition at line 712 of file log.c.

◆ tor_log_string()

void tor_log_string ( int  severity,
log_domain_mask_t  domain,
const char *  function,
const char *  string 

As tor_log, but takes an optional function name, and does not treat its string as a printf format.

For use by Rust integration.

Definition at line 271 of file log.c.

References log_fn_().

◆ tor_log_update_sigsafe_err_fds()

void void tor_log_update_sigsafe_err_fds ( void  )

Function to call whenever the list of logs changes to get ready to log from signal handlers.

Definition at line 663 of file log.c.

References logfile_t::fd, int_array_contains(), logfile_t::is_temporary, LD_BUG, LD_GENERAL, LOCK_LOGS, LOG_ERR, logfile_is_external(), logfiles, log_severity_list_t::masks, logfile_t::next, logfile_t::seems_dead, logfile_t::severities, SEVERITY_MASK_IDX, and TOR_SIGSAFE_LOG_MAX_FDS.

◆ truncate_logs()

void truncate_logs ( void  )

Truncate all the log files.

Definition at line 1480 of file log.c.

References logfile_t::fd, logfiles, logfile_t::next, and tor_ftruncate().

Variable Documentation

◆ log_global_min_severity_

int log_global_min_severity_

What's the lowest log level anybody cares about? Checking this lets us bail out early from log_debug if we aren't debugging.

Definition at line 224 of file log.c.

Referenced by add_file_log(), change_callback_log_severity(), log_fn_(), log_message_is_interesting(), switch_logs_debug(), and tor_log().


const int LOG_WARN_

This defines log levels that are linked in the Rust log module, rather than re-defining these in both Rust and C.

C_RUST_COUPLED src/rust/tor_log LogSeverity, LogDomain

Defining compile-time constants for Tor log levels (used by the Rust log wrapper at src/rust/tor_log)

Definition at line 71 of file log.c.