libfreeradius logging functions More...

#include <freeradius-devel/build.h>
#include <freeradius-devel/missing.h>
#include <freeradius-devel/util/event.h>
#include <freeradius-devel/util/fopencookie.h>
#include <freeradius-devel/util/table.h>
#include <freeradius-devel/util/talloc.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>

Include dependency graph for log.h:

Go to the source code of this file.

Data Structures
struct	fr_log_fd_event_ctx_t
	Context structure for the log fd event function. More...

struct	fr_log_perror_format_t

struct	fr_log_s

Typedefs
typedef struct fr_log_s	fr_log_t

Enumerations
enum	fr_log_dst_t { L_DST_STDOUT = 0 , L_DST_FILES , L_DST_SYSLOG , L_DST_STDERR , L_DST_FUNC , L_DST_NULL , L_DST_NUM_DEST }

enum	fr_log_lvl_t { L_DBG_LVL_DISABLE = -1 , L_DBG_LVL_OFF = 0 , L_DBG_LVL_1 , L_DBG_LVL_2 , L_DBG_LVL_3 , L_DBG_LVL_4 , L_DBG_LVL_MAX }

enum	fr_log_timestamp_t { L_TIMESTAMP_AUTO = 0 , L_TIMESTAMP_ON , L_TIMESTAMP_OFF }

enum	fr_log_type_t { L_INFO = 3 , L_ERR = 4 , L_WARN = 5 , L_AUTH = 6 , L_DBG = 16 , L_DBG_INFO = 17 , L_DBG_WARN = 18 , L_DBG_ERR = 19 , L_DBG_WARN_REQ = 20 , L_DBG_ERR_REQ = 21 }

Functions
void	fr_canonicalize_error (TALLOC_CTX ctx, char spaces, char text, ssize_t slen, char const fmt)
	Canonicalize error strings, removing tabs, and generate spaces for error marker. More...

void	fr_log (fr_log_t const log, fr_log_type_t lvl, char const file, int line, char const *fmt,...))
	Send a server log message to its destination. More...

int	fr_log_close (fr_log_t *log)
	Universal close function for all logging destinations. More...

void	fr_log_fd_event (UNUSED fr_event_list_t el, int fd, UNUSED int flags, void uctx)
	Function to provide as the readable callback to the event loop. More...

void	fr_log_global_free (void)
	Restores the original stdout and stderr FDs, closes the pipes and removes them from the event loop. More...

int	fr_log_global_init (fr_event_list_t *el, bool daemonize)
	Manipulate stderr and stdout so that was capture all data send to it from libraries. More...

void	fr_log_hex (fr_log_t const log, fr_log_type_t type, char const file, int line, uint8_t const data, size_t data_len, char const line_prefix_fmt,...))
	Print out hex block. More...

void	fr_log_hex_marker (fr_log_t const log, fr_log_type_t type, char const file, int line, uint8_t const data, size_t data_len, ssize_t marker_idx, char const marker, char const *line_prefix_fmt,...))
	Print out hex block. More...

int	fr_log_init_file (fr_log_t log, char const file)
	Initialise a file logging destination. More...

int	fr_log_init_fp (fr_log_t log, FILE fp)
	Initialise a file logging destination to a FILE*. More...

int	fr_log_init_func (fr_log_t log, cookie_write_function_t write, cookie_close_function_t close, void uctx))
	Initialise a function based logging destination. More...

int	fr_log_init_legacy (fr_log_t *log, bool daemonize)
	Initialise file descriptors based on logging destination. More...

int	fr_log_init_std (fr_log_t *log, fr_log_dst_t dst_type)
	Initialise log dst for stdout, stderr or /dev/null. More...

int	fr_log_init_syslog (fr_log_t *log)
	Initialise a syslog logging destination. More...

void	fr_log_marker (fr_log_t const log, fr_log_type_t type, char const file, int line, char const str, size_t str_len, ssize_t marker_idx, char const marker, char const *line_prefix_fmt,...))
	Print out an error marker. More...

void	fr_log_perror (fr_log_t const log, fr_log_type_t type, char const file, int line, fr_log_perror_format_t const rules, char const fmt,...))
	Drain any outstanding messages from the fr_strerror buffers. More...

TALLOC_CTX *	fr_log_pool_init (void)
	talloc ctx to use when composing log messages More...

static bool	fr_rate_limit_enabled (void)
	Whether rate limiting is enabled. More...

void	fr_vlog (fr_log_t const log, fr_log_type_t lvl, char const file, int line, char const *fmt, va_list ap))
	Send a server log message to its destination. More...

void	fr_vlog_perror (fr_log_t const log, fr_log_type_t type, char const file, int line, fr_log_perror_format_t const rules, char const fmt, va_list ap))
	Drain any outstanding messages from the fr_strerror buffers. More...

Variables
fr_log_t	default_log

int	fr_debug_lvl

FILE *	fr_log_fp

fr_table_num_ordered_t const	fr_log_levels []
	Maps log categories to message prefixes. More...

size_t	fr_log_levels_len

bool	fr_log_rate_limit
	Whether repeated log entries should be rate limited. More...

bool	log_dates_utc

Detailed Description

libfreeradius logging functions

Copyright: 2016 The FreeRADIUS server project

Definition in file log.h.

Data Structure Documentation

◆ fr_log_fd_event_ctx_t

struct fr_log_fd_event_ctx_t

Context structure for the log fd event function.

This enables a file descriptor to be inserted into an event loop and produce log output. It's useful for execd child processes and for capturing stdout/stderr from libraries.

Definition at line 135 of file log.h.

Collaboration diagram for fr_log_fd_event_ctx_t:

Data Fields
fr_log_t const *	dst	Where to log to.
fr_log_lvl_t	lvl	Priority of the message.
char const *	prefix	To add to log messages.
fr_log_type_t	type	What type of log message it is.

◆ fr_log_perror_format_t

struct fr_log_perror_format_t

Definition at line 124 of file log.h.

Data Fields
char const *	first_prefix	Prefix for the first line printed.
char const *	subsq_prefix	Prefix for subsequent lines.

Typedef Documentation

◆ fr_log_t

typedef struct fr_log_s fr_log_t

Definition at line 52 of file log.h.

Enumeration Type Documentation

◆ fr_log_dst_t

enum fr_log_dst_t

Enumerator
L_DST_STDOUT	Log to stdout.
L_DST_FILES	Log to a file on disk.
L_DST_SYSLOG	Log to syslog.
L_DST_STDERR	Log to stderr.
L_DST_FUNC	Send log messages to a FILE*, via fopencookie()
L_DST_NULL	Discard log messages.
L_DST_NUM_DEST

Definition at line 77 of file log.h.

◆ fr_log_lvl_t

enum fr_log_lvl_t

Enumerator
L_DBG_LVL_DISABLE	Don't print messages.
L_DBG_LVL_OFF	No debug messages.
L_DBG_LVL_1	Highest priority debug messages (-x).
L_DBG_LVL_2	2nd highest priority debug messages (-xx \| -X).
L_DBG_LVL_3	3rd highest priority debug messages (-xxx \| -Xx).
L_DBG_LVL_4	4th highest priority debug messages (-xxxx \| -Xxx).
L_DBG_LVL_MAX	Lowest priority debug messages (-xxxxx \| -Xxxx).

Definition at line 67 of file log.h.

◆ fr_log_timestamp_t

enum fr_log_timestamp_t

Enumerator

L_TIMESTAMP_AUTO

Timestamp logging preference not specified.

Do it based on debug level and destination.

L_TIMESTAMP_ON

Always log timestamps.

L_TIMESTAMP_OFF

Never log timestamps.

Definition at line 87 of file log.h.

◆ fr_log_type_t

enum fr_log_type_t

Enumerator
L_INFO	Informational message.
L_ERR	Error message.
L_WARN	Warning.
L_AUTH	Authentication logs.
L_DBG	Only displayed when debugging is enabled.
L_DBG_INFO	Info only displayed when debugging is enabled.
L_DBG_WARN	Warning only displayed when debugging is enabled.
L_DBG_ERR	Error only displayed when debugging is enabled.
L_DBG_WARN_REQ	Less severe warning only displayed when debugging is enabled.
L_DBG_ERR_REQ	Less severe error only displayed when debugging is enabled.

Definition at line 54 of file log.h.

Function Documentation

◆ fr_canonicalize_error()

void fr_canonicalize_error	(	TALLOC_CTX *	ctx,
		char **	sp,
		char **	text,
		ssize_t	slen,
		char const *	fmt
	)

Canonicalize error strings, removing tabs, and generate spaces for error marker.

Note: talloc_free must be called on the buffer returned in spaces and text

Used to produce error messages such as this:

 I'm a string with a parser # error
                            ^ Unexpected character in string

With code resembling this:

ERROR("%s", parsed_str);

ERROR("%s^ %s", space, text);

ERROR

#define ERROR(fmt,...)

Definition: dhcpclient.c:41

Todo:: merge with above function (log_request_marker)

Parameters

sp	Where to write a dynamically allocated buffer of spaces used to indent the error text.
text	Where to write the canonicalized version of fmt (the error text).
ctx	to allocate the spaces and text buffers in.
slen	of error marker. Expects negative integer value, as returned by parse functions.
fmt	to canonicalize.

Definition at line 89 of file log.c.

Here is the caller graph for this function:

◆ fr_log()

void fr_log	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		char const *	fmt,
			...
	)

Send a server log message to its destination.

Parameters

log	destination.
type	of log message.
file	where the log message originated
line	where the log message originated
fmt	with printf style substitution tokens.
...	Substitution arguments.

Definition at line 599 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_close()

int fr_log_close ( fr_log_t * log )

Universal close function for all logging destinations.

Definition at line 1199 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_fd_event()

void fr_log_fd_event	(	UNUSED fr_event_list_t *	el,
		int	fd,
		UNUSED int	flags,
		void *	uctx
	)

Function to provide as the readable callback to the event loop.

Writes any data read from a file descriptor to the request log, tries very hard not to chop lines in the middle, but will split at 1024 byte boundaries if forced to.

Parameters

[in]	el	UNUSED
[in]	fd	UNUSED
[in]	flags	UNUSED
[in]	uctx	Pointer to a log_fd_event_ctx_t

Definition at line 178 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_global_free()

void fr_log_global_free ( void )

Restores the original stdout and stderr FDs, closes the pipes and removes them from the event loop.

Definition at line 1354 of file log.c.

Here is the call graph for this function:

◆ fr_log_global_init()

int fr_log_global_init	(	fr_event_list_t *	el,
		bool	daemonize
	)

Manipulate stderr and stdout so that was capture all data send to it from libraries.

Parameters

[in]	el	The event list we use to process logging data.
[in]	daemonize	Whether the server is starting as a daemon.

Returns

0 on success.
-1 on failure.

Definition at line 1235 of file log.c.

Here is the call graph for this function:

◆ fr_log_hex()

void fr_log_hex	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		uint8_t const *	data,
		size_t	data_len,
		char const *	line_prefix_fmt,
			...
	)

Print out hex block.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	data	to print.
[in]	data_len	length of data.
[in]	line_prefix_fmt	Prefix to add to the marker messages.
[in]	...	Arguments for line_prefix_fmt.

Definition at line 800 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_hex_marker()

void fr_log_hex_marker	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		uint8_t const *	data,
		size_t	data_len,
		ssize_t	marker_idx,
		char const *	marker,
		char const *	line_prefix_fmt,
			...
	)

Print out hex block.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	data	to print.
[in]	data_len	length of data.
[in]	marker_idx	Where to place the marker. May be negative.
[in]	marker	text to print at marker_idx.
[in]	line_prefix_fmt	Prefix to add to the marker messages.
[in]	...	Arguments for line_prefix_fmt.

Definition at line 847 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_init_file()

int fr_log_init_file	(	fr_log_t *	log,
		char const *	file
	)

Initialise a file logging destination.

Parameters

[out]	log	Destination to initialise.
[in]	file	to open handle for.

Returns

0 on success.
-1 on failure.

Definition at line 1099 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_init_fp()

int fr_log_init_fp	(	fr_log_t *	log,
		FILE *	fp
	)

Initialise a file logging destination to a FILE*.

Parameters

[out]	log	Destination to initialise.
[in]	fp	pre-existing handle

Returns

0 on success.
-1 on failure.

Definition at line 1078 of file log.c.

Here is the caller graph for this function:

◆ fr_log_init_func()

int fr_log_init_func	(	fr_log_t *	log,
		cookie_write_function_t	write,
		cookie_close_function_t	close,
		void *	uctx
	)

Initialise a function based logging destination.

Note: Cookie functions receive the fr_log_t which contains the uctx, not the uctx directly.

Parameters

[out]	log	Destination to initialise.
[in]	write	Called when a complete log line is ready for writing.
[in]	close	May be NULL. Called when the logging destination has been closed.
[in]	uctx	for the write and close functions.

Returns

0 on success.
-1 on failure.

Definition at line 1175 of file log.c.

Here is the call graph for this function:

◆ fr_log_init_legacy()

int fr_log_init_legacy	(	fr_log_t *	log,
		bool	daemonize
	)

Initialise file descriptors based on logging destination.

Parameters

log	Logger to manipulate.
daemonize	Whether the server is starting as a daemon.

Returns

0 on success.
-1 on failure.

Definition at line 923 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_init_std()

int fr_log_init_std	(	fr_log_t *	log,
		fr_log_dst_t	dst_type
	)

Initialise log dst for stdout, stderr or /dev/null.

Parameters

[out]	log	Destination to initialise.
[in]	dst_type	The specific type of log destination to initialise.

Returns

0 on success.
-1 on failure.

Definition at line 1044 of file log.c.

Here is the caller graph for this function:

◆ fr_log_init_syslog()

int fr_log_init_syslog ( fr_log_t * log )

Initialise a syslog logging destination.

Parameters

[out] log Destination to initialise.

Returns

0 on success.
-1 on failure.

Definition at line 1145 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_marker()

void fr_log_marker	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		char const *	str,
		size_t	str_len,
		ssize_t	marker_idx,
		char const *	marker,
		char const *	line_prefix_fmt,
			...
	)

Print out an error marker.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	str	Subject string we're printing a marker for.
[in]	str_len	Subject string length. Use SIZE_MAX for the length of the string.
[in]	marker_idx	Where to place the marker. May be negative.
[in]	marker	text to print at marker_idx.
[in]	line_prefix_fmt	Prefix to add to the marker messages.
[in]	...	Arguments for line_prefix_fmt.

Definition at line 750 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_perror()

void fr_log_perror	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		fr_log_perror_format_t const *	rules,
		char const *	fmt,
			...
	)

Drain any outstanding messages from the fr_strerror buffers.

This function drains any messages from fr_strerror buffer adding a prefix (fmt) to the first message.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	rules	for printing multiline errors.
[in]	fmt	with printf style substitution tokens.
[in]	...	Substitution arguments.

Definition at line 725 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_log_pool_init()

TALLOC_CTX* fr_log_pool_init ( void )

talloc ctx to use when composing log messages

Functions must ensure that they allocate a new ctx from the one returned here, and that this ctx is freed before the function returns.

Returns: talloc pool to use for scratch space.

Definition at line 315 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_rate_limit_enabled()

static bool fr_rate_limit_enabled ( void )

inlinestatic

Whether rate limiting is enabled.

Definition at line 148 of file log.h.

Here is the caller graph for this function:

◆ fr_vlog()

void fr_vlog	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		char const *	fmt,
		va_list	ap
	)

Send a server log message to its destination.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	fmt	with printf style substitution tokens.
[in]	ap	Substitution arguments.

Definition at line 343 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_vlog_perror()

void fr_vlog_perror	(	fr_log_t const *	log,
		fr_log_type_t	type,
		char const *	file,
		int	line,
		fr_log_perror_format_t const *	f_rules,
		char const *	fmt,
		va_list	ap
	)

Drain any outstanding messages from the fr_strerror buffers.

This function drains any messages from fr_strerror buffer prefixing the first message with fmt + args.

If a prefix is specified in rules, this is prepended to all lines logged. The prefix is useful for adding context, i.e. configuration file and line number information.

Parameters

[in]	log	destination.
[in]	type	of log message.
[in]	file	src file the log message was generated in.
[in]	line	number the log message was generated on.
[in]	f_rules	for printing multiline errors.
[in]	fmt	with printf style substitution tokens.
[in]	ap	Substitution arguments.

Definition at line 630 of file log.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ default_log

fr_log_t default_log

extern

Definition at line 290 of file log.c.

◆ fr_debug_lvl

int fr_debug_lvl

extern

Definition at line 42 of file log.c.

◆ fr_log_fp

FILE* fr_log_fp

extern

Definition at line 41 of file log.c.

◆ fr_log_levels

fr_table_num_ordered_t const fr_log_levels[]

extern

Maps log categories to message prefixes.

Definition at line 244 of file log.c.

◆ fr_log_levels_len

size_t fr_log_levels_len

extern

Definition at line 256 of file log.c.

◆ fr_log_rate_limit

bool fr_log_rate_limit

extern

Whether repeated log entries should be rate limited.

Definition at line 60 of file log.c.

◆ log_dates_utc

bool log_dates_utc

extern

Definition at line 288 of file log.c.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ fr_log_fd_event_ctx_t

◆ fr_log_perror_format_t

Typedef Documentation

◆ fr_log_t

Enumeration Type Documentation

◆ fr_log_dst_t

◆ fr_log_lvl_t

◆ fr_log_timestamp_t

◆ fr_log_type_t

Function Documentation

◆ fr_canonicalize_error()

◆ fr_log()

◆ fr_log_close()

◆ fr_log_fd_event()

◆ fr_log_global_free()

◆ fr_log_global_init()

◆ fr_log_hex()

◆ fr_log_hex_marker()

◆ fr_log_init_file()

◆ fr_log_init_fp()

◆ fr_log_init_func()

◆ fr_log_init_legacy()

◆ fr_log_init_std()

◆ fr_log_init_syslog()

◆ fr_log_marker()

◆ fr_log_perror()

◆ fr_log_pool_init()

◆ fr_rate_limit_enabled()

◆ fr_vlog()

◆ fr_vlog_perror()

Variable Documentation

◆ default_log

◆ fr_debug_lvl

◆ fr_log_fp

◆ fr_log_levels

◆ fr_log_levels_len

◆ fr_log_rate_limit

◆ log_dates_utc