logging.h File Reference

Logging Dispatcher. More...

#include <stdbool.h>
#include <stdio.h>
#include <time.h>
#include "queue.h"

Include dependency graph for logging.h:

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

Go to the source code of this file.

Data Structures
struct	LogLine
	A Log line. More...

Macros
#define	mutt_debug(LEVEL, ...)   MuttLogger(0, __FILE__, __LINE__, __func__, LEVEL, __VA_ARGS__)
#define	mutt_warning(...)   MuttLogger(0, __FILE__, __LINE__, __func__, LL_WARNING, __VA_ARGS__)
#define	mutt_message(...)   MuttLogger(0, __FILE__, __LINE__, __func__, LL_MESSAGE, __VA_ARGS__)
#define	mutt_error(...)   MuttLogger(0, __FILE__, __LINE__, __func__, LL_ERROR, __VA_ARGS__)
#define	mutt_perror(...)   MuttLogger(0, __FILE__, __LINE__, __func__, LL_PERROR, __VA_ARGS__)

Typedefs
typedef int(*	log_dispatcher_t) (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
	Prototype for a logging function. More...

Enumerations
enum	LogLevel {   LL_PERROR = -3, LL_ERROR = -2, LL_WARNING = -1, LL_MESSAGE = 0,   LL_DEBUG1 = 1, LL_DEBUG2 = 2, LL_DEBUG3 = 3, LL_DEBUG4 = 4,   LL_DEBUG5 = 5, LL_NOTIFY = 6, LL_MAX }
	Names for the Logging Levels. More...

Functions
	STAILQ_HEAD (LogLineList, LogLine)
int	log_disp_file (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
	Save a log line to a file. More...
int	log_disp_null (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
	Discard log lines - Implements log_dispatcher_t. More...
int	log_disp_queue (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
	Save a log line to an internal queue - Implements log_dispatcher_t. More...
int	log_disp_terminal (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
	Save a log line to the terminal - Implements log_dispatcher_t. More...
int	log_queue_add (struct LogLine *ll)
	Add a LogLine to the queue. More...
void	log_queue_empty (void)
	Free the contents of the queue. More...
void	log_queue_flush (log_dispatcher_t disp)
	Replay the log queue. More...
int	log_queue_save (FILE *fp)
	Save the contents of the queue to a temporary file. More...
void	log_queue_set_max_size (int size)
	Set a upper limit for the queue length. More...
void	log_file_close (bool verbose)
	Close the log file. More...
int	log_file_open (bool verbose)
	Start logging to a file. More...
bool	log_file_running (void)
	Is the log file running? More...
int	log_file_set_filename (const char *file, bool verbose)
	Set the filename for the log. More...
int	log_file_set_level (enum LogLevel level, bool verbose)
	Set the logging level. More...
void	log_file_set_version (const char *version)
	Set the program's version number. More...

Variables
log_dispatcher_t	MuttLogger
	The log dispatcher. More...

Detailed Description

Logging Dispatcher.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file logging.h.

Macro Definition Documentation

mutt_debug

#define mutt_debug	(		LEVEL,
			...
	)		MuttLogger(0, __FILE__, __LINE__, __func__, LEVEL, __VA_ARGS__)

Definition at line 81 of file logging.h.

mutt_warning

#define mutt_warning

(

...

)

MuttLogger(0, __FILE__, __LINE__, __func__, LL_WARNING, __VA_ARGS__)

Definition at line 82 of file logging.h.

mutt_message

#define mutt_message

(

...

)

MuttLogger(0, __FILE__, __LINE__, __func__, LL_MESSAGE, __VA_ARGS__)

Definition at line 83 of file logging.h.

mutt_error

#define mutt_error

(

...

)

MuttLogger(0, __FILE__, __LINE__, __func__, LL_ERROR, __VA_ARGS__)

Definition at line 84 of file logging.h.

mutt_perror

#define mutt_perror

(

...

)

MuttLogger(0, __FILE__, __LINE__, __func__, LL_PERROR, __VA_ARGS__)

Definition at line 85 of file logging.h.

Typedef Documentation

log_dispatcher_t

typedef int(* log_dispatcher_t) (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)

Prototype for a logging function.

Parameters

stamp	Unix time (optional)
file	Source file
line	Source line
function	Source function
level	Logging level, e.g. LL_WARNING
...	Format string and parameters, like printf()

Return values

-1	Error
0	Success, filtered
>0	Success, number of characters written

Definition at line 62 of file logging.h.

Enumeration Type Documentation

LogLevel

enum LogLevel

Names for the Logging Levels.

Enumerator
LL_PERROR	Log perror (using errno)
LL_ERROR	Log error.
LL_WARNING	Log warning.
LL_MESSAGE	Log informational message.
LL_DEBUG1	Log at debug level 1.
LL_DEBUG2	Log at debug level 2.
LL_DEBUG3	Log at debug level 3.
LL_DEBUG4	Log at debug level 4.
LL_DEBUG5	Log at debug level 5.
LL_NOTIFY	Log of notifications.
LL_MAX

Definition at line 34 of file logging.h.

{
  LL_PERROR  = -3, 
  LL_ERROR   = -2, 
  LL_WARNING = -1, 
  LL_MESSAGE =  0, 
  LL_DEBUG1  =  1, 
  LL_DEBUG2  =  2, 
  LL_DEBUG3  =  3, 
  LL_DEBUG4  =  4, 
  LL_DEBUG5  =  5, 
  LL_NOTIFY  =  6, 

  LL_MAX,
};

Function Documentation

STAILQ_HEAD()

STAILQ_HEAD	(	LogLineList	,
		LogLine
	)

log_disp_file()

int log_disp_file	(	time_t	stamp,
		const char *	file,
		int	line,
		const char *	function,
		enum LogLevel	level,
			...
	)

Save a log line to a file.

Parameters

stamp	Unix time (optional)
file	Source file (UNUSED)
line	Source line (UNUSED)
function	Source function
level	Logging level, e.g. LL_WARNING
...	Format string and parameters, like printf()

Return values

-1	Error
0	Success, filtered
>0	Success, number of characters written

This log dispatcher saves a line of text to a file. The format is:

• [TIMESTAMP]<LEVEL> FUNCTION() FORMATTED-MESSAGE

The caller must first set LogFileName and LogFileLevel, then call log_file_open(). Any logging above LogFileLevel will be ignored.

If stamp is 0, then the current time will be used.

Definition at line 255 of file logging.c.

{
  if (!LogFileFP || (level < LL_PERROR) || (level > LogFileLevel))
    return 0;

  int ret = 0;
  int err = errno;

  if (!function)
    function = "UNKNOWN";

  ret += fprintf(LogFileFP, "[%s]<%c> %s() ", timestamp(stamp),
                 LevelAbbr[level + 3], function);

  va_list ap;
  va_start(ap, level);
  const char *fmt = va_arg(ap, const char *);
  ret += vfprintf(LogFileFP, fmt, ap);
  va_end(ap);

  if (level == LL_PERROR)
  {
    fprintf(LogFileFP, ": %s\n", strerror(err));
  }
  else if (level <= LL_MESSAGE)
  {
    fputs("\n", LogFileFP);
    ret++;
  }

  return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_disp_null()

int log_disp_null	(	time_t	stamp,
		const char *	file,
		int	line,
		const char *	function,
		enum LogLevel	level,
			...
	)

Discard log lines - Implements log_dispatcher_t.

Definition at line 515 of file logging.c.

{
  return 0;
}

Here is the caller graph for this function:

log_disp_queue()

int log_disp_queue	(	time_t	stamp,
		const char *	file,
		int	line,
		const char *	function,
		enum LogLevel	level,
			...
	)

Save a log line to an internal queue - Implements log_dispatcher_t.

This log dispatcher saves a line of text to a queue. The format string and parameters are expanded and the other parameters are stored as they are.

See also

log_queue_set_max_size(), log_queue_flush(), log_queue_empty()

Warning

Log lines are limited to 1024 bytes.

Definition at line 409 of file logging.c.

{
  char buf[1024] = { 0 };
  int err = errno;

  va_list ap;
  va_start(ap, level);
  const char *fmt = va_arg(ap, const char *);
  int ret = vsnprintf(buf, sizeof(buf), fmt, ap);
  va_end(ap);

  if (level == LL_PERROR)
  {
    ret += snprintf(buf + ret, sizeof(buf) - ret, ": %s", strerror(err));
    level = LL_ERROR;
  }

  struct LogLine *ll = mutt_mem_calloc(1, sizeof(*ll));
  ll->time = (stamp != 0) ? stamp : mutt_date_epoch();
  ll->file = file;
  ll->line = line;
  ll->function = function;
  ll->level = level;
  ll->message = mutt_str_strdup(buf);

  log_queue_add(ll);

  return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_disp_terminal()

int log_disp_terminal	(	time_t	stamp,
		const char *	file,
		int	line,
		const char *	function,
		enum LogLevel	level,
			...
	)

Save a log line to the terminal - Implements log_dispatcher_t.

This log dispatcher saves a line of text to the terminal. The format is:

• [TIMESTAMP]<LEVEL> FUNCTION() FORMATTED-MESSAGE

Note

The output will be coloured using ANSI escape sequences, unless the output is redirected.

Definition at line 450 of file logging.c.

{
  if ((level < LL_PERROR) || (level > LL_MESSAGE))
    return 0;

  char buf[1024];

  va_list ap;
  va_start(ap, level);
  const char *fmt = va_arg(ap, const char *);
  int ret = vsnprintf(buf, sizeof(buf), fmt, ap);
  va_end(ap);

  log_disp_file(stamp, file, line, function, level, "%s", buf);

  FILE *fp = (level < LL_MESSAGE) ? stderr : stdout;
  int err = errno;
  int colour = 0;
  bool tty = (isatty(fileno(fp)) == 1);

  if (tty)
  {
    switch (level)
    {
      case LL_PERROR:
      case LL_ERROR:
        colour = 31;
        break;
      case LL_WARNING:
        colour = 33;
        break;
      case LL_MESSAGE:
        // colour = 36;
        break;
      case LL_DEBUG1:
      case LL_DEBUG2:
      case LL_DEBUG3:
      case LL_DEBUG4:
      case LL_DEBUG5:
      case LL_NOTIFY:
      default:
        break;
    }
  }

  if (colour > 0)
    ret += fprintf(fp, "\033[1;%dm", colour); // Escape

  fputs(buf, fp);

  if (level == LL_PERROR)
    ret += fprintf(fp, ": %s", strerror(err));

  if (colour > 0)
    ret += fprintf(fp, "\033[0m"); // Escape

  ret += fprintf(fp, "\n");

  return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_queue_add()

int log_queue_add

(

struct LogLine *

ll

)

Add a LogLine to the queue.

Parameters

ll	LogLine to add

Return values

num	Entries in the queue

If LogQueueMax is non-zero, the queue will be limited to this many items.

Definition at line 296 of file logging.c.

{
  if (!ll)
    return -1;

  STAILQ_INSERT_TAIL(&LogQueue, ll, entries);

  if ((LogQueueMax > 0) && (LogQueueCount >= LogQueueMax))
  {
    ll = STAILQ_FIRST(&LogQueue);
    STAILQ_REMOVE_HEAD(&LogQueue, entries);
    FREE(&ll->message);
    FREE(&ll);
  }
  else
  {
    LogQueueCount++;
  }
  return LogQueueCount;
}

Here is the caller graph for this function:

log_queue_empty()

void log_queue_empty

(

void

)

Free the contents of the queue.

Free any log lines in the queue.

Definition at line 335 of file logging.c.

{
  struct LogLine *ll = NULL;
  struct LogLine *tmp = NULL;

  STAILQ_FOREACH_SAFE(ll, &LogQueue, entries, tmp)
  {
    STAILQ_REMOVE(&LogQueue, ll, LogLine, entries);
    FREE(&ll->message);
    FREE(&ll);
  }

  LogQueueCount = 0;
}

Here is the caller graph for this function:

log_queue_flush()

void log_queue_flush

(

log_dispatcher_t

disp

)

Replay the log queue.

Parameters

disp	Log dispatcher - Implements log_dispatcher_t

Pass all of the log entries in the queue to the log dispatcher provided. The queue will be emptied afterwards.

Definition at line 357 of file logging.c.

{
  struct LogLine *ll = NULL;
  STAILQ_FOREACH(ll, &LogQueue, entries)
  {
    disp(ll->time, ll->file, ll->line, ll->function, ll->level, "%s", ll->message);
  }

  log_queue_empty();
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_queue_save()

int log_queue_save

(

FILE *

fp

)

Save the contents of the queue to a temporary file.

Parameters

fp	Open file handle

Return values

num	Lines written to the file

The queue is written to a temporary file. The format is:

• [HH:MM:SS]<LEVEL> FORMATTED-MESSAGE

Note

The caller should free the returned string and delete the file.

Definition at line 378 of file logging.c.

{
  if (!fp)
    return 0;

  char buf[32];
  int count = 0;
  struct LogLine *ll = NULL;
  STAILQ_FOREACH(ll, &LogQueue, entries)
  {
    mutt_date_localtime_format(buf, sizeof(buf), "%H:%M:%S", ll->time);
    fprintf(fp, "[%s]<%c> %s", buf, LevelAbbr[ll->level + 3], ll->message);
    if (ll->level <= LL_MESSAGE)
      fputs("\n", fp);
    count++;
  }

  return count;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_queue_set_max_size()

void log_queue_set_max_size

(

int

size

)

Set a upper limit for the queue length.

Parameters

size	New maximum queue length

Note

size of 0 means unlimited

Definition at line 323 of file logging.c.

{
  if (size < 0)
    size = 0;
  LogQueueMax = size;
}

Here is the caller graph for this function:

log_file_close()

void log_file_close

(

bool

verbose

)

Close the log file.

Parameters

verbose

If true, then log the event

Definition at line 98 of file logging.c.

{
  if (!LogFileFP)
    return;

  fprintf(LogFileFP, "[%s] Closing log.\n", timestamp(0));
  fprintf(LogFileFP, "# vim: syntax=neomuttlog\n");
  mutt_file_fclose(&LogFileFP);
  if (verbose)
    mutt_message(_("Closed log file: %s"), LogFileName);
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_file_open()

int log_file_open

(

bool

verbose

)

Start logging to a file.

Parameters

verbose

If true, then log the event

Return values

0	Success
-1	Error, see errno

Before opening a log file, call log_file_set_version(), log_file_set_level() and log_file_set_filename().

Definition at line 119 of file logging.c.

{
  if (!LogFileName)
    return -1;

  if (LogFileFP)
    log_file_close(false);

  if (LogFileLevel < LL_DEBUG1)
    return -1;

  LogFileFP = mutt_file_fopen(LogFileName, "a+");
  if (!LogFileFP)
    return -1;
  setvbuf(LogFileFP, NULL, _IOLBF, 0);

  fprintf(LogFileFP, "[%s] NeoMutt%s debugging at level %d\n", timestamp(0),
          NONULL(LogFileVersion), LogFileLevel);
  if (verbose)
    mutt_message(_("Debugging at level %d to file '%s'"), LogFileLevel, LogFileName);
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_file_running()

bool log_file_running

(

void

)

Is the log file running?

Return values

true	If the log file is running

Definition at line 230 of file logging.c.

{
  return LogFileFP;
}

Here is the caller graph for this function:

log_file_set_filename()

int log_file_set_filename	(	const char *	file,
		bool	verbose
	)

Set the filename for the log.

Parameters

file	Name to use
verbose	If true, then log the event

Return values

0	Success, file opened
-1	Error, see errno

Definition at line 149 of file logging.c.

{
  if (!file)
    return -1;

  /* also handles both being NULL */
  if (mutt_str_strcmp(LogFileName, file) == 0)
    return 0;

  mutt_str_replace(&LogFileName, file);

  if (!LogFileName)
    log_file_close(verbose);

  return log_file_open(verbose);
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_file_set_level()

int log_file_set_level	(	enum LogLevel	level,
		bool	verbose
	)

Set the logging level.

Parameters

level	Logging level
verbose	If true, then log the event

Return values

0	Success
-1	Error, level is out of range

The level should be: LL_MESSAGE <= level < LL_MAX.

Definition at line 175 of file logging.c.

{
  if ((level < LL_MESSAGE) || (level >= LL_MAX))
    return -1;

  if (level == LogFileLevel)
    return 0;

  LogFileLevel = level;

  if (level == LL_MESSAGE)
  {
    log_file_close(verbose);
  }
  else if (LogFileFP)
  {
    if (verbose)
      mutt_message(_("Logging at level %d to file '%s'"), LogFileLevel, LogFileName);
    fprintf(LogFileFP, "[%s] NeoMutt%s debugging at level %d\n", timestamp(0),
            NONULL(LogFileVersion), LogFileLevel);
  }
  else
  {
    log_file_open(verbose);
  }

  if (LogFileLevel >= LL_DEBUG5)
  {
    fprintf(LogFileFP,
            "\n"
            "WARNING:\n"
            "    Logging at this level can reveal personal information.\n"
            "    Review the log carefully before posting in bug reports.\n"
            "\n");
  }

  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

log_file_set_version()

void log_file_set_version

(

const char *

version

)

Set the program's version number.

Parameters

version

Version number

The string will be appended directly to 'NeoMutt', so it should begin with a hyphen.

Definition at line 221 of file logging.c.

{
  mutt_str_replace(&LogFileVersion, version);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

MuttLogger

log_dispatcher_t MuttLogger

The log dispatcher.

This function pointer controls where log messages are redirected.

Definition at line 52 of file logging.c.