.\" Copyright (c) 2018-2023, OARC, Inc.
.\" All rights reserved.
.\"
.\" This file is part of dnsjit.
.\"
.\" dnsjit 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 3 of the License, or
.\" (at your option) any later version.
.\"
.\" dnsjit 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 dnsjit.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsjit.core.log 3 "1.3.0" "dnsjit"
.SH NAME
dnsjit.core.log \- Core logging facility
.SH SYNOPSIS
.SS Usage to control global log level
  local log = require("dnsjit.core.log")
  log.enable("all")
  log.disable("debug")
.SS Usage to control module log level
  local example = require("example") -- Example as below
  example.log():enable("all")
  example.log():disable("debug")
.SS Usage to control object instance log level
  local example = require("example") -- Example as below
  local obj = example.new()
  obj:log():enable("all")
  obj:log():disable("debug")
.SS Usage in C module
.B NOTE
naming of variables and module only globals are required to exactly as
described in order for the macros to work;
.B self
is the pointer to the object instance,
.B self->_log
is the object instance logging configuration struct,
.B _log
is the module logging configuration struct.
.LP
Include logging:
  #include "core/log.h"
.LP
Add the logging struct to the module struct:
  typedef struct example {
      core_log_t _log;
      ...
  } example_t;
.LP
Add a module logging configuration and a struct default:
  static core_log_t _log = LOG_T_INIT("example");
  static example_t _defaults = {
      LOG_T_INIT_OBJ("example"),
      ...
  };
.LP
Use new/free and/or init/destroy functions (depends if you create the
object in Lua or not):
  example_t* example_new() {
      example_t* self = calloc(1, sizeof(example_t));

      *self = _defaults;
      ldebug("new()");

      return self;
  }

  void example_free(example_t* self) {
      ldebug("free()");
      free(self);
  }

  int example_init(example_t* self) {
      *self = _defaults;

      ldebug("init()");

      return 0;
  }

  void example_destroy(example_t* self) {
      ldebug("destroy()");
      ...
  }
.LP
In the Lua part of the C module you need to create a function that
returns either the object instance Log or the modules Log.
.LP
Add C function to get module only Log:
  core_log_t* example_log() {
      return &_log;
  }
.LP
For the structures metatable add the following function:
  local ffi = require("ffi")
  local C = ffi.C

  function Example:log()
      if self == nil then
          return C.example_log()
      end
      return self._log
  end
.SS Usage in pure Lua module
  local log = require("dnsjit.core.log")
  local ffi = require("ffi")
  local C = ffi.C

  local Example = {}
  local module_log = log.new("example")

  function Example.new()
      local self = setmetatable({
          _log = log.new("example", module_log),
      }, { __index = Example })

      self._log:debug("new()")

      return self
  end

  function Example:log()
      if self == nil then
          return module_log
      end
      return self._log
  end
.SH DESCRIPTION
Core logging facility used by all modules.
.SS Log levels
.TP
all
Keyword to enable/disable all changeable log levels.
.TP
debug
Used for debug information.
.TP
info
Used for informational processing messages.
.TP
notice
Used for messages of that may have impact on processing.
.TP
warning
Used for messages that has impact on processing.
.TP
critical
Used for messages that have severe impact on processing, this level can
not be disabled.
.TP
fatal
Used to display a message before stopping all processing and existing,
this level can not be disabled.
.SS C macros
.TP
Object instance macros
The following macros uses
.IR &self->_log :
.BR ldebug(msg...) ,
.BR linfo(msg...) ,
.BR lnotice(msg...) ,
.BR lwarning(msg...) ,
.BR lcritical(msg...) ,
.BR lfatal(msg...) .
.TP
Object pointer instance macros
The following macros uses
.IR self->_log :
.BR lpdebug(msg...) ,
.BR lpinfo(msg...) ,
.BR lpnotice(msg...) ,
.BR lpwarning(msg...) ,
.BR lpcritical(msg...) ,
.BR lpfatal(msg...) .
.TP
Module macros
The following macros uses
.IR &_log :
.BR mldebug(msg...) ,
.BR mlinfo(msg...) ,
.BR mlnotice(msg...) ,
.BR mlwarning(msg...) ,
.BR mlcritical(msg...) ,
.BR mlfatal(msg...) .
.TP
Global macros
The following macros uses the global logging configuration:
.BR gldebug(msg...) ,
.BR glinfo(msg...) ,
.BR glnotice(msg...) ,
.BR glwarning(msg...) ,
.BR glcritical(msg...) ,
.BR glfatal(msg...) .
.SS Functions
.TP
.BR Log.new "(name, module)"
Create a new Log object with the given module
.I name
and an optional shared
.I module
Log object.
.TP
.BR Log:enable "(level)"
Enable specified log level.
.TP
.BR Log:disable "(level)"
Disable specified log level.
.TP
.BR Log:clear "(level)"
Clear specified log level, which means it will revert back to default
or inherited settings.
.TP
.BR Log:display_file_line "(bool)"
Enable or disable the displaying of file and line for messages.
.TP
.BR Log.errstr "(errno)"
Convert error number to its text representation.
.TP
.BR Log.debug "(self, ...)"
Generate a debug message.
.TP
.BR Log.info "(self, ...)"
Generate an info message.
.TP
.BR Log.notice "(self, ...)"
Generate a notice message.
.TP
.BR Log.warning "(self, ...)"
Generate a warning message.
.TP
.BR Log.critical "(self, ...)"
Generate a critical message.
.TP
.BR Log.fatal "(self, ...)"
Generate a fatal message.
.SH AUTHORS and CONTRIBUTORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC),
Petr Špaček (ISC)
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fIhttps://github.com/DNS-OARC/dnsjit/issues\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fIadmin@dns-oarc.net\fP
.RE
.LP