NeoMutt  2024-03-23-147-g885fbc
Teaching an old dog new tricks
DOXYGEN
Loading...
Searching...
No Matches
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 -.
 
static 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_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_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
stampUnix time (optional)
fileSource file
lineSource line
functionSource function
levelLogging level, e.g. LL_WARNING
formatprintf()-style formatting string
...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 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.

76{
77 char buf[LOG_LINE_MAX_LEN] = { 0 };
78 size_t buflen = sizeof(buf);
79 int err = errno;
80 int colour = 0;
81 int bytes = 0;
82
83 if (DebugLogColor)
84 {
85 switch (level)
86 {
87 case LL_PERROR:
88 case LL_ERROR:
89 colour = 31;
90 break;
91 case LL_WARNING:
92 colour = 33;
93 break;
94 case LL_MESSAGE:
95 default:
96 break;
97 }
98
99 if (colour > 0)
100 {
101 bytes += snprintf(buf + bytes, buflen - bytes, "\033[1;%dm", colour); // Escape
102 }
103 }
104
106 {
107 bytes += log_timestamp(buf + bytes, buflen - bytes, stamp);
108 }
109
110 if (DebugLogLevel)
111 {
112 bytes += log_level(buf + bytes, buflen - bytes, level);
113 }
114
115 va_list ap;
116 va_start(ap, format);
117 bytes += vsnprintf(buf + bytes, buflen - bytes, format, ap);
118 va_end(ap);
119
120 if (level == LL_PERROR)
121 bytes += snprintf(buf + bytes, buflen - bytes, ": %s", strerror(err));
122
123 if (colour > 0)
124 {
125 bytes += snprintf(buf + bytes, buflen - bytes, "\033[0m"); // Escape
126 }
127
128 if (level < LL_DEBUG1)
129 bytes += snprintf(buf + bytes, buflen - bytes, "\n");
130
131 fputs(buf, stdout);
132 return bytes;
133}
bool DebugLogLevel
Prefix log level, e.g. [E].
Definition: logging.c:40
static int log_level(char *buf, size_t buflen, enum LogLevel level)
Write a log level to a buffer.
Definition: logging.c:66
bool DebugLogColor
Output ANSI colours.
Definition: logging.c:39
static int log_timestamp(char *buf, size_t buflen, time_t time)
Write a timestamp to a buffer.
Definition: logging.c:52
bool DebugLogTimestamp
Show the timestamp.
Definition: logging.c:41
@ LL_ERROR
Log error.
Definition: logging2.h:40
@ LL_PERROR
Log perror (using errno)
Definition: logging2.h:39
@ LL_WARNING
Log warning.
Definition: logging2.h:41
@ LL_MESSAGE
Log informational message.
Definition: logging2.h:42
@ LL_DEBUG1
Log at debug level 1.
Definition: logging2.h:43
#define LOG_LINE_MAX_LEN
Log lines longer than this will be truncated.
Definition: logging2.h:32
+ Here is the call graph for this function:

◆ log_disp_null()

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

Discard log lines - Implements log_dispatcher_t -.

Definition at line 16 of file address.c.

18{
19 return 0;
20}
+ Here is the caller 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 246 of file logging.c.

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

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

443{
444 char buf[LOG_LINE_MAX_LEN] = { 0 };
445
446 va_list ap;
447 va_start(ap, format);
448 int rc = vsnprintf(buf, sizeof(buf), format, ap);
449 va_end(ap);
450
451 log_disp_file(stamp, file, line, function, level, "%s", buf);
452
453 if ((level < LL_PERROR) || (level > LL_MESSAGE))
454 return 0;
455
456 FILE *fp = (level < LL_MESSAGE) ? stderr : stdout;
457 int err = errno;
458 int color = 0;
459 bool tty = (isatty(fileno(fp)) == 1);
460
461 if (tty)
462 {
463 switch (level)
464 {
465 case LL_PERROR:
466 case LL_ERROR:
467 color = 31;
468 break;
469 case LL_WARNING:
470 color = 33;
471 break;
472 case LL_MESSAGE:
473 default:
474 break;
475 }
476 }
477
478 if (color > 0)
479 rc += fprintf(fp, "\033[1;%dm", color); // Escape
480
481 fputs(buf, fp);
482
483 if (level == LL_PERROR)
484 rc += fprintf(fp, ": %s", strerror(err));
485
486 if (color > 0)
487 rc += fprintf(fp, "\033[0m"); // Escape
488
489 rc += fprintf(fp, "\n");
490
491 return rc;
492}
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 -.
Definition: logging.c:246
+ Here is the call graph for this function:
+ 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.

90{
91 const short c_debug_level = cs_subset_number(NeoMutt->sub, "debug_level");
92 if (level > c_debug_level)
93 return 0;
94
95 char buf[LOG_LINE_MAX_LEN] = { 0 };
96
97 va_list ap;
98 va_start(ap, format);
99 int rc = vsnprintf(buf, sizeof(buf), format, ap);
100 va_end(ap);
101
102 if ((level == LL_PERROR) && (rc >= 0) && (rc < sizeof(buf)))
103 {
104 char *buf2 = buf + rc;
105 int len = sizeof(buf) - rc;
106 const char *p = strerror(errno);
107 if (!p)
108 p = _("unknown error");
109
110 rc += snprintf(buf2, len, ": %s (errno = %d)", p, errno);
111 }
112
113 const bool dupe = (mutt_str_equal(buf, ErrorBuf));
114 if (!dupe)
115 {
116 /* Only log unique messages */
117 log_disp_file(stamp, file, line, function, level, "%s", buf);
118 if (stamp == 0)
119 log_disp_queue(stamp, file, line, function, level, "%s", buf);
120 }
121
122 /* Don't display debugging message on screen */
123 if (level > LL_MESSAGE)
124 return 0;
125
126 /* Only pause if this is a message following an error */
127 if ((level > LL_ERROR) && OptMsgErr && !dupe)
128 error_pause();
129
130 mutt_str_copy(ErrorBuf, buf, sizeof(ErrorBuf));
131 ErrorBufMessage = true;
132
133 if (!OptKeepQuiet)
134 {
135 enum ColorId cid = MT_COLOR_NORMAL;
136 switch (level)
137 {
138 case LL_ERROR:
139 mutt_beep(false);
140 cid = MT_COLOR_ERROR;
141 break;
142 case LL_WARNING:
143 cid = MT_COLOR_WARNING;
144 break;
145 default:
146 cid = MT_COLOR_MESSAGE;
147 break;
148 }
149
150 msgwin_set_text(NULL, ErrorBuf, cid);
151 }
152
153 if ((level <= LL_ERROR) && !dupe)
154 {
155 OptMsgErr = true;
157 }
158 else
159 {
160 OptMsgErr = false;
161 LastError = 0;
162 }
163
165 return rc;
166}
ColorId
List of all colored objects.
Definition: color.h:40
@ MT_COLOR_MESSAGE
Informational message.
Definition: color.h:57
@ MT_COLOR_ERROR
Error message.
Definition: color.h:51
@ MT_COLOR_NORMAL
Plain text.
Definition: color.h:59
@ MT_COLOR_WARNING
Warning messages.
Definition: color.h:81
short cs_subset_number(const struct ConfigSubset *sub, const char *name)
Get a number config item by name.
Definition: helpers.c:144
void mutt_beep(bool force)
Irritate the user.
Definition: curs_lib.c:68
bool OptKeepQuiet
(pseudo) shut up the message and refresh functions while we are executing an external program
Definition: globals.c:66
char ErrorBuf[1024]
Copy of the last error message.
Definition: globals.c:36
bool OptMsgErr
(pseudo) used by mutt_error/mutt_message
Definition: globals.c:67
bool ErrorBufMessage
true if the last message was an error
Definition: globals.c:35
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 -.
Definition: logging.c:398
struct MuttWindow * msgwin_get_window(void)
Get the Message Window pointer.
Definition: msgwin.c:530
void msgwin_set_text(struct MuttWindow *win, const char *text, enum ColorId color)
Set the text for the Message Window.
Definition: msgwin.c:484
uint64_t mutt_date_now_ms(void)
Return the number of milliseconds since the Unix epoch.
Definition: date.c:464
#define _(a)
Definition: message.h:28
bool mutt_str_equal(const char *a, const char *b)
Compare two strings.
Definition: string.c:709
size_t mutt_str_copy(char *dest, const char *src, size_t dsize)
Copy a string into a buffer (guaranteeing NUL-termination)
Definition: string.c:630
static uint64_t LastError
Time of the last error message (in milliseconds since the Unix epoch)
Definition: mutt_logging.c:47
static void error_pause(void)
Wait for an error message to be read.
Definition: mutt_logging.c:59
void window_redraw(struct MuttWindow *win)
Reflow, recalc and repaint a tree of Windows.
Definition: mutt_window.c:634
Container for Accounts, Notifications.
Definition: neomutt.h:41
struct ConfigSubset * sub
Inherited config items.
Definition: neomutt.h:45
+ 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 53 of file logging.c.