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,...)

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 - Implements log_dispatcher_t -. 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.

Typedef Documentation

log_dispatcher_t

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

Definition at line 65 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_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 285 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 324 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 346 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 delete the file

Definition at line 367 of file logging.c.

{
  if (!fp)
    return 0;
 
  char buf[32] = { 0 };
  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 312 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	The log file is running

Definition at line 229 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_equal(LogFileName, file))
    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 220 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: