Logging API

Prototype for a Logging Function. More...

Macros
#define	mutt_debug(LEVEL, ...)
#define	mutt_warning(...)
#define	mutt_message(...)
#define	mutt_error(...)
#define	mutt_perror(...)

Functions
int	log_disp_debug (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Display a log line on screen - Implements log_dispatcher_t -.
int	log_disp_file (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Save a log line to a file - Implements log_dispatcher_t -.
int	log_disp_queue (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Save a log line to an internal queue - Implements log_dispatcher_t -.
int	log_disp_terminal (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Save a log line to the terminal - Implements log_dispatcher_t -.
int	log_disp_null (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Discard log lines - Implements log_dispatcher_t -.
int	log_disp_curses (time_t stamp, const char *file, int line, const char *function, enum LogLevel level, const char *format,...)
	Display a log line in the message line - Implements log_dispatcher_t -.

Variables
log_dispatcher_t	MuttLogger = log_disp_terminal
	The log dispatcher -.

Detailed Description

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	printf()-style formatting string
...	Parameters, like printf()

Return values

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

Macro Definition Documentation

mutt_debug

#define mutt_debug	(		LEVEL,
			... )

Value:

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

Definition at line 91 of file logging2.h.

mutt_warning

#define mutt_warning

(

...

)

Value:

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

Definition at line 92 of file logging2.h.

mutt_message

#define mutt_message

(

...

)

Value:

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

Definition at line 93 of file logging2.h.

mutt_error

#define mutt_error

(

...

)

Value:

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

Definition at line 94 of file logging2.h.

mutt_perror

#define mutt_perror

(

...

)

Value:

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

Definition at line 95 of file logging2.h.

Function Documentation

log_disp_debug()

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

Display a log line on screen - Implements log_dispatcher_t -.

Definition at line 74 of file logging.c.

{
  char buf[LOG_LINE_MAX_LEN] = { 0 };
  size_t buflen = sizeof(buf);
  int err = errno;
  int colour = 0;
  int bytes = 0;
 
  if (DebugLogColor)
  {
    switch (level)
    {
      case LL_PERROR:
      case LL_ERROR:
        colour = 31;
        break;
      case LL_WARNING:
        colour = 33;
        break;
      case LL_MESSAGE:
      default:
        break;
    }
 
    if (colour > 0)
    {
      bytes += snprintf(buf + bytes, buflen - bytes, "\033[1;%dm", colour); // Escape
    }
  }
 
  if (DebugLogTimestamp)
  {
    bytes += log_timestamp(buf + bytes, buflen - bytes, stamp);
  }
 
  if (DebugLogLevel)
  {
    bytes += log_level(buf + bytes, buflen - bytes, level);
  }
 
  va_list ap;
  va_start(ap, format);
  bytes += vsnprintf(buf + bytes, buflen - bytes, format, ap);
  va_end(ap);
 
  if (level == LL_PERROR)
    bytes += snprintf(buf + bytes, buflen - bytes, ": %s", strerror(err));
 
  if (colour > 0)
  {
    bytes += snprintf(buf + bytes, buflen - bytes, "\033[0m"); // Escape
  }
 
  if (level < LL_DEBUG1)
    bytes += snprintf(buf + bytes, buflen - bytes, "\n");
 
  fputs(buf, stdout);
  return bytes;
}

Here is the call graph for this function:

log_disp_file()

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

Save a log line to a file - Implements log_dispatcher_t -.

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 252 of file logging.c.

{
  if (!LogFileFP || (level < LL_PERROR) || (level > LogFileLevel))
    return 0;
 
  int rc = 0;
  int err = errno;
 
  if (!function)
    function = "UNKNOWN";
 
  rc += fprintf(LogFileFP, "[%s]<%c> %s() ", timestamp(stamp),
                LogLevelAbbr[level + 3], function);
 
  va_list ap;
  va_start(ap, format);
  rc += vfprintf(LogFileFP, format, ap);
  va_end(ap);
 
  if (level == LL_PERROR)
  {
    fprintf(LogFileFP, ": %s\n", strerror(err));
  }
  else if (level <= LL_MESSAGE)
  {
    fputs("\n", LogFileFP);
    rc++;
  }
 
  return rc;
}

Here is the call graph for this function:

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,
		const char *	format,
			... )

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 LOG_LINE_MAX_LEN bytes

Definition at line 384 of file logging.c.

{
  char buf[LOG_LINE_MAX_LEN] = { 0 };
  int err = errno;
 
  va_list ap;
  va_start(ap, format);
  int rc = vsnprintf(buf, sizeof(buf), format, ap);
  va_end(ap);
 
  if (level == LL_PERROR)
  {
    if ((rc >= 0) && (rc < sizeof(buf)))
      rc += snprintf(buf + rc, sizeof(buf) - rc, ": %s", strerror(err));
    level = LL_ERROR;
  }
 
  struct LogLine *ll = MUTT_MEM_CALLOC(1, struct LogLine);
  ll->time = (stamp != 0) ? stamp : mutt_date_now();
  ll->file = file;
  ll->line = line;
  ll->function = function;
  ll->level = level;
  ll->message = mutt_str_dup(buf);
 
  log_queue_add(ll);
 
  return rc;
}

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,
		const char *	format,
			... )

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

Warning

Log lines are limited to LOG_LINE_MAX_LEN bytes

Note

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

Definition at line 427 of file logging.c.

{
  char buf[LOG_LINE_MAX_LEN] = { 0 };
 
  va_list ap;
  va_start(ap, format);
  int rc = vsnprintf(buf, sizeof(buf), format, ap);
  va_end(ap);
 
  log_disp_file(stamp, file, line, function, level, "%s", buf);
 
  if ((level < LL_PERROR) || (level > LL_MESSAGE))
    return 0;
 
  FILE *fp = (level < LL_MESSAGE) ? stderr : stdout;
  int err = errno;
  int color = 0;
  bool tty = (isatty(fileno(fp)) == 1);
 
  if (tty)
  {
    switch (level)
    {
      case LL_PERROR:
      case LL_ERROR:
        color = 31;
        break;
      case LL_WARNING:
        color = 33;
        break;
      case LL_MESSAGE:
      default:
        break;
    }
  }
 
  if (color > 0)
    rc += fprintf(fp, "\033[1;%dm", color); // Escape
 
  fputs(buf, fp);
 
  if (level == LL_PERROR)
    rc += fprintf(fp, ": %s", strerror(err));
 
  if (color > 0)
    rc += fprintf(fp, "\033[0m"); // Escape
 
  rc += fprintf(fp, "\n");
 
  return rc;
}

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,
		const char *	format,
			... )

Discard log lines - Implements log_dispatcher_t -.

This log dispatcher simply discards all log messages. It can be used to disable logging when it isn't needed, such as in tests and fuzzers.

Definition at line 515 of file logging.c.

{
  return 0;
}

Here is the caller graph for this function:

log_disp_curses()

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

Display a log line in the message line - Implements log_dispatcher_t -.

Definition at line 88 of file mutt_logging.c.

{
  const short c_debug_level = cs_subset_number(NeoMutt->sub, "debug_level");
  if (level > c_debug_level)
    return 0;
 
  char buf[LOG_LINE_MAX_LEN] = { 0 };
 
  va_list ap;
  va_start(ap, format);
  int rc = vsnprintf(buf, sizeof(buf), format, ap);
  va_end(ap);
 
  if ((level == LL_PERROR) && (rc >= 0) && (rc < sizeof(buf)))
  {
    char *buf2 = buf + rc;
    int len = sizeof(buf) - rc;
    const char *p = strerror(errno);
    if (!p)
      p = _("unknown error");
 
    rc += snprintf(buf2, len, ": %s (errno = %d)", p, errno);
  }
 
  const bool dupe = (mutt_str_equal(buf, ErrorBuf));
  if (!dupe)
  {
    /* Only log unique messages */
    log_disp_file(stamp, file, line, function, level, "%s", buf);
    if (stamp == 0)
      log_disp_queue(stamp, file, line, function, level, "%s", buf);
  }
 
  /* Don't display debugging message on screen */
  if (level > LL_MESSAGE)
    return 0;
 
  /* Only pause if this is a message following an error */
  if ((level > LL_ERROR) && OptMsgErr && !dupe)
    error_pause();
 
  mutt_str_copy(ErrorBuf, buf, sizeof(ErrorBuf));
  ErrorBufMessage = true;
 
  if (!OptKeepQuiet)
  {
    enum ColorId cid = MT_COLOR_NORMAL;
    switch (level)
    {
      case LL_ERROR:
        mutt_beep(false);
        cid = MT_COLOR_ERROR;
        break;
      case LL_WARNING:
        cid = MT_COLOR_WARNING;
        break;
      default:
        cid = MT_COLOR_MESSAGE;
        break;
    }
 
    msgwin_set_text(NULL, ErrorBuf, cid);
  }
 
  if ((level <= LL_ERROR) && !dupe)
  {
    OptMsgErr = true;
    LastError = mutt_date_now_ms();
  }
  else
  {
    OptMsgErr = false;
    LastError = 0;
  }
 
  window_redraw(msgwin_get_window());
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

MuttLogger

log_dispatcher_t MuttLogger = log_disp_terminal

The log dispatcher -.

This function pointer controls where log messages are redirected.

Definition at line 54 of file logging.c.