NeoMutt  2021-02-05-666-ge300cd
Teaching an old dog new tricks
DOXYGEN
Logging API

The Logging API. 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_file (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
 Save a log line to a file - Implements log_dispatcher_t -This log dispatcher saves a line of text to a file. 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 -This log dispatcher saves a line of text to a queue. 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 -This log dispatcher saves a line of text to the terminal. 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_curses (time_t stamp, const char *file, int line, const char *function, enum LogLevel level,...)
 Display a log line in the message line - Implements log_dispatcher_t -. More...
 

Variables

log_dispatcher_t MuttLogger = log_disp_terminal
 The log dispatcher -This function pointer controls where log messages are redirected. More...
 

Detailed Description

The Logging API.

Prototype for a logging function

Parameters
stampUnix time (optional)
fileSource file
lineSource line
functionSource function
levelLogging level, e.g. LL_WARNING
...Format string and parameters, like printf()
Return values
-1Error
0Success, filtered
>0Success, number of characters written

Macro Definition Documentation

◆ mutt_debug

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

Definition at line 85 of file logging.h.

◆ mutt_warning

#define mutt_warning (   ...)    MuttLogger(0, __FILE__, __LINE__, __func__, LL_WARNING, __VA_ARGS__)

Definition at line 86 of file logging.h.

◆ mutt_message

#define mutt_message (   ...)    MuttLogger(0, __FILE__, __LINE__, __func__, LL_MESSAGE, __VA_ARGS__)

Definition at line 87 of file logging.h.

◆ mutt_error

#define mutt_error (   ...)    MuttLogger(0, __FILE__, __LINE__, __func__, LL_ERROR, __VA_ARGS__)

Definition at line 88 of file logging.h.

◆ mutt_perror

#define mutt_perror (   ...)    MuttLogger(0, __FILE__, __LINE__, __func__, LL_PERROR, __VA_ARGS__)

Definition at line 89 of file logging.h.

Function Documentation

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

248 {
249  if (!LogFileFP || (level < LL_PERROR) || (level > LogFileLevel))
250  return 0;
251 
252  int ret = 0;
253  int err = errno;
254 
255  if (!function)
256  function = "UNKNOWN";
257 
258  ret += fprintf(LogFileFP, "[%s]<%c> %s() ", timestamp(stamp),
259  LevelAbbr[level + 3], function);
260 
261  va_list ap;
262  va_start(ap, level);
263  const char *fmt = va_arg(ap, const char *);
264  ret += vfprintf(LogFileFP, fmt, ap);
265  va_end(ap);
266 
267  if (level == LL_PERROR)
268  {
269  fprintf(LogFileFP, ": %s\n", strerror(err));
270  }
271  else if (level <= LL_MESSAGE)
272  {
273  fputs("\n", LogFileFP);
274  ret++;
275  }
276 
277  return ret;
278 }
const char * LevelAbbr
Abbreviations of logging level names.
Definition: logging.c:45
FILE * LogFileFP
Log file handle.
Definition: logging.c:54
Log perror (using errno)
Definition: logging.h:36
static const char * timestamp(time_t stamp)
Create a YYYY-MM-DD HH:MM:SS timestamp.
Definition: logging.c:77
Log informational message.
Definition: logging.h:39
int LogFileLevel
Log file level.
Definition: logging.c:56
+ 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,
  ... 
)

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

402 {
403  char buf[1024] = { 0 };
404  int err = errno;
405 
406  va_list ap;
407  va_start(ap, level);
408  const char *fmt = va_arg(ap, const char *);
409  int ret = vsnprintf(buf, sizeof(buf), fmt, ap);
410  va_end(ap);
411 
412  if (level == LL_PERROR)
413  {
414  ret += snprintf(buf + ret, sizeof(buf) - ret, ": %s", strerror(err));
415  level = LL_ERROR;
416  }
417 
418  struct LogLine *ll = mutt_mem_calloc(1, sizeof(*ll));
419  ll->time = (stamp != 0) ? stamp : mutt_date_epoch();
420  ll->file = file;
421  ll->line = line;
422  ll->function = function;
423  ll->level = level;
424  ll->message = mutt_str_dup(buf);
425 
426  log_queue_add(ll);
427 
428  return ret;
429 }
time_t mutt_date_epoch(void)
Return the number of seconds since the Unix epoch.
Definition: date.c:427
Log error.
Definition: logging.h:37
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
enum LogLevel level
Log level, e.g. LL_DEBUG1.
Definition: logging.h:79
char * message
Message to be logged.
Definition: logging.h:80
Log perror (using errno)
Definition: logging.h:36
char * mutt_str_dup(const char *str)
Copy a string, safely.
Definition: string.c:370
int line
Line number in source file.
Definition: logging.h:77
A Log line.
Definition: logging.h:73
time_t time
Timestamp of the message.
Definition: logging.h:75
const char * file
Source file.
Definition: logging.h:76
int log_queue_add(struct LogLine *ll)
Add a LogLine to the queue.
Definition: logging.c:287
const char * function
C function.
Definition: logging.h:78
+ 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 441 of file logging.c.

443 {
444  char buf[1024];
445 
446  va_list ap;
447  va_start(ap, level);
448  const char *fmt = va_arg(ap, const char *);
449  int ret = vsnprintf(buf, sizeof(buf), fmt, ap);
450  va_end(ap);
451 
452  log_disp_file(stamp, file, line, function, level, "%s", buf);
453 
454  if ((level < LL_PERROR) || (level > LL_MESSAGE))
455  return 0;
456 
457  FILE *fp = (level < LL_MESSAGE) ? stderr : stdout;
458  int err = errno;
459  int colour = 0;
460  bool tty = (isatty(fileno(fp)) == 1);
461 
462  if (tty)
463  {
464  switch (level)
465  {
466  case LL_PERROR:
467  case LL_ERROR:
468  colour = 31;
469  break;
470  case LL_WARNING:
471  colour = 33;
472  break;
473  case LL_MESSAGE:
474  // colour = 36;
475  break;
476  case LL_DEBUG1:
477  case LL_DEBUG2:
478  case LL_DEBUG3:
479  case LL_DEBUG4:
480  case LL_DEBUG5:
481  case LL_NOTIFY:
482  default:
483  break;
484  }
485  }
486 
487  if (colour > 0)
488  ret += fprintf(fp, "\033[1;%dm", colour); // Escape
489 
490  fputs(buf, fp);
491 
492  if (level == LL_PERROR)
493  ret += fprintf(fp, ": %s", strerror(err));
494 
495  if (colour > 0)
496  ret += fprintf(fp, "\033[0m"); // Escape
497 
498  ret += fprintf(fp, "\n");
499 
500  return ret;
501 }
Log at debug level 4.
Definition: logging.h:43
Log error.
Definition: logging.h:37
enum LogLevel level
Log level, e.g. LL_DEBUG1.
Definition: logging.h:79
Log of notifications.
Definition: logging.h:45
Log perror (using errno)
Definition: logging.h:36
Log informational message.
Definition: logging.h:39
int line
Line number in source file.
Definition: logging.h:77
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 - Implements log_dispatcher_t -This log dispatcher saves a line of text to ...
Definition: logging.c:246
Log at debug level 2.
Definition: logging.h:41
Log at debug level 1.
Definition: logging.h:40
Log at debug level 5.
Definition: logging.h:44
const char * file
Source file.
Definition: logging.h:76
Log at debug level 3.
Definition: logging.h:42
Log warning.
Definition: logging.h:38
+ 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 506 of file logging.c.

508 {
509  return 0;
510 }

◆ log_disp_curses()

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

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

Definition at line 126 of file mutt_logging.c.

128 {
129  const short c_debug_level = cs_subset_number(NeoMutt->sub, "debug_level");
130  if (level > c_debug_level)
131  return 0;
132 
133  char buf[1024];
134 
135  va_list ap;
136  va_start(ap, level);
137  const char *fmt = va_arg(ap, const char *);
138  int ret = vsnprintf(buf, sizeof(buf), fmt, ap);
139  va_end(ap);
140 
141  if (level == LL_PERROR)
142  {
143  char *buf2 = buf + ret;
144  int len = sizeof(buf) - ret;
145  const char *p = strerror(errno);
146  if (!p)
147  p = _("unknown error");
148 
149  ret += snprintf(buf2, len, ": %s (errno = %d)", p, errno);
150  }
151 
152  const bool dupe = (strcmp(buf, ErrorBuf) == 0);
153  if (!dupe)
154  {
155  /* Only log unique messages */
156  log_disp_file(stamp, file, line, function, level, "%s", buf);
157  if (stamp == 0)
158  log_disp_queue(stamp, file, line, function, level, "%s", buf);
159  }
160 
161  /* Don't display debugging message on screen */
162  if (level > LL_MESSAGE)
163  return 0;
164 
165  /* Only pause if this is a message following an error */
166  if ((level > LL_ERROR) && OptMsgErr && !dupe)
167  error_pause();
168 
169  size_t width = msgwin_get_width();
170  mutt_simple_format(ErrorBuf, sizeof(ErrorBuf), 0, width ? width : sizeof(ErrorBuf),
171  JUSTIFY_LEFT, 0, buf, sizeof(buf), false);
172  ErrorBufMessage = true;
173 
174  if (!OptKeepQuiet)
175  {
176  enum ColorId color = MT_COLOR_NORMAL;
177  switch (level)
178  {
179  case LL_ERROR:
180  mutt_beep(false);
181  color = MT_COLOR_ERROR;
182  break;
183  case LL_WARNING:
184  color = MT_COLOR_WARNING;
185  break;
186  default:
187  color = MT_COLOR_MESSAGE;
188  break;
189  }
190 
191  msgwin_set_text(color, ErrorBuf);
192  }
193 
194  if ((level <= LL_ERROR) && !dupe)
195  {
196  OptMsgErr = true;
198  }
199  else
200  {
201  OptMsgErr = false;
202  LastError = 0;
203  }
204 
205  return ret;
206 }
Log error.
Definition: logging.h:37
uint64_t mutt_date_epoch_ms(void)
Return the number of milliseconds since the Unix epoch.
Definition: date.c:436
Left justify the text.
Definition: curs_lib.h:43
enum LogLevel level
Log level, e.g. LL_DEBUG1.
Definition: logging.h:79
Informational message.
Definition: color.h:56
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 ...
Definition: logging.c:400
size_t msgwin_get_width(void)
Get the width of the Message Window.
Definition: msgwin.c:262
Log perror (using errno)
Definition: logging.h:36
#define _(a)
Definition: message.h:28
uint64_t LastError
Time of the last error message (in milliseconds since the Unix epoch)
Definition: mutt_logging.c:46
Log informational message.
Definition: logging.h:39
WHERE char ErrorBuf[256]
Copy of the last error message.
Definition: mutt_globals.h:43
short cs_subset_number(const struct ConfigSubset *sub, const char *name)
Get a number config item by name.
Definition: helpers.c:169
Container for Accounts, Notifications.
Definition: neomutt.h:36
int line
Line number in source file.
Definition: logging.h:77
void mutt_beep(bool force)
Irritate the user.
Definition: curs_lib.c:105
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 - Implements log_dispatcher_t -This log dispatcher saves a line of text to ...
Definition: logging.c:246
ColorId
List of all colored objects.
Definition: color.h:39
Plain text.
Definition: color.h:58
Error message.
Definition: color.h:51
WHERE bool OptMsgErr
(pseudo) used by mutt_error/mutt_message
Definition: options.h:40
struct ConfigSubset * sub
Inherited config items.
Definition: neomutt.h:39
WHERE bool ErrorBufMessage
true if the last message was an error
Definition: mutt_globals.h:42
static void error_pause(void)
Wait for an error message to be read.
Definition: mutt_logging.c:58
WHERE bool OptKeepQuiet
(pseudo) shut up the message and refresh functions while we are executing an external program ...
Definition: options.h:38
const char * file
Source file.
Definition: logging.h:76
Warning messages.
Definition: color.h:79
void mutt_simple_format(char *buf, size_t buflen, int min_width, int max_width, enum FormatJustify justify, char pad_char, const char *s, size_t n, bool arboreal)
Format a string, like snprintf()
Definition: curs_lib.c:716
Log warning.
Definition: logging.h:38
void msgwin_set_text(enum ColorId color, const char *text)
Set the text for the Message Window.
Definition: msgwin.c:223
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Variable Documentation

◆ MuttLogger

The log dispatcher -This function pointer controls where log messages are redirected.

Definition at line 52 of file logging.c.