torlog.h File Reference

Headers for log.c. More...

#include "compat.h"
#include "testsupport.h"

Include dependency graph for torlog.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	log_severity_list_t

Macros
#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	N_LOGGING_DOMAINS   26
#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, ...)
#define	TOR_TORLOG_H

Typedefs
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)

Functions
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, const int truncate)
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_err_sigsafe (const char *m,...)
int	tor_log_get_sigsafe_err_fds (const int **out)
void	tor_log_update_sigsafe_err_fds (void)
void	tor_log_get_logfile_names (struct smartlist_t *out)
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)

Variables
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.

Macro Definition Documentation

LD_ACCT

#define LD_ACCT   (1u<<17)

Bandwidth accounting.

LD_APP

#define LD_APP   (1u<<8)

Application (socks) requests.

LD_BUG

#define LD_BUG   (1u<<12)

Internal errors in this Tor process.

LD_CHANNEL

#define LD_CHANNEL   (1u<<21)

Abstract channel_t code

LD_CIRC

#define LD_CIRC   (1u<<10)

Building, using, and managing circuits.

LD_CONFIG

#define LD_CONFIG   (1u<<3)

Parsing and acting on our configuration.

LD_CONSDIFF

#define LD_CONSDIFF   (1u<<24)

Generation and application of consensus diffs.

LD_CONTROL

#define LD_CONTROL   (1u<<9)

Communication via the controller protocol.

LD_CRYPTO

#define LD_CRYPTO   (1u<<1)

The cryptography subsystem.

LD_DIR

#define LD_DIR   (1u<<13)

Learning and using information about Tor servers.

LD_DIRSERV

#define LD_DIRSERV   (1u<<14)

Learning and using information about Tor servers.

LD_DOS

#define LD_DOS   (1u<<25)

Denial of Service mitigation.

LD_EDGE

#define LD_EDGE   (1u<<16)

Generic edge-connection functionality.

LD_FS

#define LD_FS   (1u<<4)

Reading and writing from the filesystem.

LD_GENERAL

#define LD_GENERAL   (1u<<0)

Catch-all for miscellaneous events and fatal errors.

LD_GUARD

#define LD_GUARD   (1u<<23)

Guard nodes

LD_HANDSHAKE

#define LD_HANDSHAKE   (1u<<19)

OR handshaking

LD_HEARTBEAT

#define LD_HEARTBEAT   (1u<<20)

Heartbeat messages

LD_HIST

#define LD_HIST   (1u<<18)

Router history

LD_HTTP

#define LD_HTTP   (1u<<7)

HTTP implementation.

LD_MM

#define LD_MM   (1u<<6)

Memory management.

LD_NET

#define LD_NET   (1u<<2)

Networking.

LD_NOCB

#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.

LD_NOFUNCNAME

#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.

LD_OR

#define LD_OR   (1u<<15)

Onion routing protocol.

LD_PROTOCOL

#define LD_PROTOCOL   (1u<<5)

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

LD_REND

#define LD_REND   (1u<<11)

Hidden services.

LD_SCHED

#define LD_SCHED   (1u<<22)

Scheduler

LOG_DEBUG

#define LOG_DEBUG   7

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

log_debug

#define log_debug	(		domain,
			args,
			...
	)

Value:

STMT_BEGIN                                                                \
    if (PREDICT_UNLIKELY(log_global_min_severity_ == LOG_DEBUG))            \
      log_fn_(LOG_DEBUG, domain, __FUNCTION__, args, ##__VA_ARGS__); \
  STMT_END

LOG_ERR

#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.

log_fn

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

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

log_fn_ratelim

#define log_fn_ratelim	(		ratelim,
			severity,
			domain,
			args,
			...
	)

Value:

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.

LOG_INFO

#define LOG_INFO   6

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

LOG_NOTICE

#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.

LOG_WARN

#define LOG_WARN   4

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

N_LOGGING_DOMAINS

#define N_LOGGING_DOMAINS   26

Number of logging domains in the code.

Typedef Documentation

log_callback

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

Callback type used for add_callback_log.

log_domain_mask_t

typedef uint32_t log_domain_mask_t

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

log_severity_list_t

typedef struct log_severity_list_t 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.

add_file_log()

int add_file_log	(	const log_severity_list_t *	severity,
		const char *	filename,
		const int	truncate_log
	)

Add a log handler to send messages to filename. If opening the logfile fails, -1 is returned and errno is set appropriately (by open(2)).

Here is the call graph for this function:

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.

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).

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.

Here is the call graph for this function:

Here is the caller graph for this function:

close_temp_logs()

void close_temp_logs

(

void

)

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

Here is the caller graph for this function:

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.

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.

get_min_log_level()

int get_min_log_level

(

void

)

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

Here is the caller graph for this function:

init_logging()

void init_logging

(

int

disable_startup_queue

)

Initialize the global logging facility

Here is the call graph for this function:

Here is the caller graph for this function:

log_level_to_string()

const char* log_level_to_string

(

int

level

)

Return the string equivalent of a given log level.

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.

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.

Here is the caller graph for this function:

logs_free_all()

void logs_free_all

(

void

)

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

logs_set_domain_logging()

void logs_set_domain_logging

(

int

enabled

)

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

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".

mark_logs_temp()

void mark_logs_temp

(

void

)

Configure all log handles to be closed by close_temp_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.

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the caller graph for this function:

set_log_time_granularity()

void set_log_time_granularity

(

int

granularity_msec

)

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

switch_logs_debug()

void switch_logs_debug

(

void

)

Switch all logs to output at most verbose level.

Here is the call graph for this function:

tor_log_err_sigsafe()

void void tor_log_err_sigsafe	(	const char *	m,
			...
	)

Given a list of string arguments ending with a NULL, writes them to our logs and to stderr (if possible). This function is safe to call from within a signal handler.

Here is the call graph for this function:

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.

tor_log_get_sigsafe_err_fds()

int tor_log_get_sigsafe_err_fds

(

const int **

out

)

Set *out to a pointer to an array of the fds to log errors to from inside a signal handler. Return the number of elements in the array.

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.

Here is the call graph for this function:

tor_log_update_sigsafe_err_fds()

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.

truncate_logs()

void truncate_logs

(

void

)

Truncate all the log files.

Here is the call graph for this function:

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.

LOG_WARN_

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)