Logging API

Prototype for a Logging Function. 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__)

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
...	Format string and 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,
			...
	)		MuttLogger(0, __FILE__, __LINE__, __func__, LEVEL, __VA_ARGS__)

Definition at line 89 of file logging2.h.

mutt_warning

#define mutt_warning

(

...

)

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

Definition at line 90 of file logging2.h.

mutt_message

#define mutt_message

(

...

)

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

Definition at line 91 of file logging2.h.

mutt_error

#define mutt_error

(

...

)

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

Definition at line 92 of file logging2.h.

mutt_perror

#define mutt_perror

(

...

)

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

Definition at line 93 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
  }
 
  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 245 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), LevelAbbr[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 397 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, sizeof(*ll));
  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 440 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 -.

Definition at line 496 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 87 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 52 of file logging.c.