The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Data Structures | Typedefs | Enumerations | Functions | Variables
log.h File Reference

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

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

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

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

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

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);
#define ERROR(fmt,...)
Definition: dhcpclient.c:41
Todo:
merge with above function (log_request_marker)
Parameters
spWhere to write a dynamically allocated buffer of spaces used to indent the error text.
textWhere to write the canonicalized version of fmt (the error text).
ctxto allocate the spaces and text buffers in.
slenof error marker. Expects negative integer value, as returned by parse functions.
fmtto canonicalize.

Definition at line 90 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
logdestination.
typeof log message.
filewhere the log message originated
linewhere the log message originated
fmtwith printf style substitution tokens.
...Substitution arguments.

Definition at line 583 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 1189 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]elUNUSED
[in]fdUNUSED
[in]flagsUNUSED
[in]uctxPointer to a log_fd_event_ctx_t

Definition at line 179 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 1344 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]elThe event list we use to process logging data.
[in]daemonizeWhether the server is starting as a daemon.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1225 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]datato print.
[in]data_lenlength of data.
[in]line_prefix_fmtPrefix to add to the marker messages.
[in]...Arguments for line_prefix_fmt.

Definition at line 784 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]datato print.
[in]data_lenlength of data.
[in]marker_idxWhere to place the marker. May be negative.
[in]markertext to print at marker_idx.
[in]line_prefix_fmtPrefix to add to the marker messages.
[in]...Arguments for line_prefix_fmt.

Definition at line 831 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]logDestination to initialise.
[in]fileto open handle for.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1083 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]logDestination to initialise.
[in]fppre-existing handle
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1062 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]logDestination to initialise.
[in]writeCalled when a complete log line is ready for writing.
[in]closeMay be NULL. Called when the logging destination has been closed.
[in]uctxfor the write and close functions.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1165 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
logLogger to manipulate.
daemonizeWhether the server is starting as a daemon.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 907 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]logDestination to initialise.
[in]dst_typeThe specific type of log destination to initialise.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1028 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]logDestination to initialise.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1135 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]strSubject string we're printing a marker for.
[in]str_lenSubject string length. Use SIZE_MAX for the length of the string.
[in]marker_idxWhere to place the marker. May be negative.
[in]markertext to print at marker_idx.
[in]line_prefix_fmtPrefix to add to the marker messages.
[in]...Arguments for line_prefix_fmt.

Definition at line 734 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]rulesfor printing multiline errors.
[in]fmtwith printf style substitution tokens.
[in]...Substitution arguments.

Definition at line 709 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 316 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]fmtwith printf style substitution tokens.
[in]apSubstitution arguments.

Definition at line 344 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]logdestination.
[in]typeof log message.
[in]filesrc file the log message was generated in.
[in]linenumber the log message was generated on.
[in]f_rulesfor printing multiline errors.
[in]fmtwith printf style substitution tokens.
[in]apSubstitution arguments.

Definition at line 614 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 291 of file log.c.

◆ fr_debug_lvl

int fr_debug_lvl
extern

Definition at line 43 of file log.c.

◆ fr_log_fp

FILE* fr_log_fp
extern

Definition at line 42 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 245 of file log.c.

◆ fr_log_levels_len

size_t fr_log_levels_len
extern

Definition at line 257 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 61 of file log.c.

◆ log_dates_utc

bool log_dates_utc
extern

Definition at line 289 of file log.c.