Logging

Logging facilities for libstephen.

Author
Stephen Brennan
Date
Created Sunday, 24 May 2015
Copyright
Copyright (c) 2015-2016, Stephen Brennan. Released under the Revised BSD License. See LICENSE.txt for details.

Defines

LEVEL_NOTSET

Most fine grained log level – loggers will report everything.

LEVEL_DEBUG

Suggested log level for messages useful for debugging.

LEVEL_INFO

Suggested log level for informational messages.

LEVEL_WARNING

Suggested log level for warning messages.

LEVEL_ERROR

Suggested log level for error messages.

LEVEL_CRITICAL

Suggested log level for critical, non-recoverable error messages.

SMB_MAX_LOGHANDLERS

Max number of log handlers to be held by a logger.

SMB_DEFAULT_LOGLEVEL

The level that the default logger starts at.

SMB_DEFAULT_LOGDEST

The file that the default logger points at.

SMB_DEFAULT_LOGFORMAT

The format string for default loggers.

This is kinda obnoxious because you can only change the formatting characters. The order of the arguments is set in stone, and you can’t change that with a format string. The order is filename:line, function, level, message.

LOG(logger, level, ...)

Log a message.

This macro fills out the file, line, and function parameters of sl_log() so that you only need to figure out the logger, level, and message.

Parameters
  • logger: Logger to log to.
  • level: Level the message is at.
  • ...: Format string and format arguments.

DDEBUG(...)

Log to default logger at LEVEL_DEBUG.

Parameters
  • ...: Format string and format arguments.

DINFO(...)

Log to default logger at LEVEL_INFO.

Parameters
  • ...: Format string and format arguments.

DWARNING(...)

Log to default logger at LEVEL_WARNING.

Parameters
  • ...: Format string and format arguments.

DERROR(...)

Log to default logger at LEVEL_ERROR.

Parameters
  • ...: Format string and format arguments.

DCRITICAL(...)

Log to default logger at LEVEL_CRITICAL.

Parameters
  • ...: Format string and format arguments.

LDEBUG(logger, ...)

Log to any logger at LEVEL_DEBUG.

Parameters
  • logger: Logger to log to.
  • ...: Format string and format arguments.

LINFO(logger, ...)

Log to any logger at LEVEL_INFO.

Parameters
  • logger: Logger to log to.
  • ...: Format string and format arguments.

LWARNING(logger, ...)

Log to any logger at LEVEL_WARNING.

Parameters
  • logger: Logger to log to.
  • ...: Format string and format arguments.

LERROR(logger, ...)

Log to any logger at LEVEL_ERROR.

Parameters
  • logger: Logger to log to.
  • ...: Format string and format arguments.

LCRITICAL(logger, ...)

Log to any logger at LEVEL_CRITICAL.

Parameters
  • logger: Logger to log to.
  • ...: Format string and format arguments.

Functions

void sl_init(smb_logger * obj)

Initialize a logger object.

Parameters
  • obj: Logger to initialize.

smb_logger* sl_create()

Allocate and return a logger object.

Return
New logger.

void sl_destroy(smb_logger * obj)

Free resources held by a logger object.

Parameters
  • obj: Logger to deinitialize.

void sl_delete(smb_logger * obj)

Free resources and deallocate a logger object.

Parameters
  • obj: Logger to deallocate.

void sl_set_level(smb_logger * l, int level)

Set the minimum level this logger will report.

All loghandlers have levels, but log messages are first filtered by the log level of the logger. If the logger is set to have a higher level, then messages won’t even get sent to the handler. The level is inclusive.

Parameters
  • l: The logger to set the level of. (NULL for default)
  • level: The level to set. Can be any integer, but specifically one of the `LEVEL_*` constants would be good.

void sl_add_handler(smb_logger * l, smb_loghandler h, smb_status * status)

Add a log handler to the logger.

Loggers have limited space for loghandlers, so this could fail. Loggers are not intended to be array lists containing arbitrary amounts of handlers, and they’re not intended to provide convenient access, update, or removal.

Parameters
  • l: Logger to add to. (NULL for default)
  • h: Handler to add to the logger.
  • status: For error reporting.
Exceptions
  • SMB_INDEX_ERROR: If there is no more space for any more handlers.

void sl_clear_handlers(smb_logger * l)

Remove all handlers from the logger.

Parameters
  • l: Logger to clear out. (NULL for default)

void sl_set_default_logger(smb_logger * l)

Set the static default logger to be your own.

When you use the `D*` logger macros, the default logger is the one you log to. The default logger will report everything to stderr, unless you modify it or set the default logger to a new one.

Parameters
  • l: New logger. NULL to reset it to the original one.

void sl_log(smb_logger * l, char * file, int line, const char * function, int level, ...)

Log a message.

This is the function that actually carries out any logging operation. All the logging macros expand to a call to this function. You really don’t want to call this function directly, cause you have to provide a ton of information that you can’t keep up to date in code, and it can all be provided by preprocessor macros.

Parameters
  • l: Logger to send log message to.
  • file: Name of the code file the message originated from.
  • line: Line number of the log message.
  • function: Name of the function the message came from.
  • level: The log level of this message.
  • ...: Format string and format arguments, forming the actual message.

struct smb_loghandler
#include <log.h>

Specifies a log handler.

This struct contains the information necessary to deliver a log message to its destination. It has no memory management functions, since you should just pass it by value.

Public Members

int level

The minimum level this log handler accepts.

FILE* dst

The destination file to send to.

struct smb_logger
#include <log.h>

Specifies a logger.

This struct represents a logger. You can create it dynamically, but it is entirely possible to create a “literal” for it and declare it statically.

Public Members

smb_loghandler handlers[SMB_MAX_LOGHANDLERS]

List of log handlers.

See
SMB_MAX_LOGHANDLERS

char* format

Format string to use for this logger.

int num

The number of handlers actually contained in the handlers array.