fixes #543 Add logging support framework

6 files changed, 217 insertions, 0 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index 9e3e8128..ba3508d2 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -115,6 +115,10 @@ if (NNG_ENABLE_DOC)
             nng_listener_set
             nng_listener_setopt
             nng_listener_start
+            nng_log
+            nng_log_set_facility
+            nng_log_set_loevel
+            nng_log_set_logger
             nng_msg_alloc
             nng_msg_append
             nng_msg_body
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 7153b14f..3e2900aa 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -283,6 +283,16 @@ universal resource locators (URLS).
 |xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string
 |===
 
+=== Logging Support
+
+Common functionality for message logging.
+
+|===
+|xref:nng_log.3.adoc[nng_log()]|log a message
+|xref:nng_log_facility.3.adoc[nng_log_set_facility()]|set log facility
+|xref:nng_log_level.3.adoc[nng_log_set_level()]|set log level
+|xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler
+|===
 
 === Supplemental API
 
diff --git a/docs/man/nng_log.3.adoc b/docs/man/nng_log.3.adoc
new file mode 100644
index 00000000..852f765b
--- /dev/null
+++ b/docs/man/nng_log.3.adoc
@@ -0,0 +1,62 @@
+= nng_log(3)
+//
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_log - log messages
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_log_err(const char *msgid, const char *msg, ...);
+void nng_log_warn(const char *msgid, const char *msg, ...);
+void nng_log_notice(const char *msgid, const char *msg, ...);
+void nng_log_info(const char *msgid, const char *msg, ...);
+void nng_log_debug(const char *msgid, const char *msg, ...);
+
+void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...);
+----
+
+== DESCRIPTION
+
+These functions are used to post a message to system or application logs.
+
+The first five forms all post a message at the severity indicated by the function name.
+The _msgid_ should be a short message identifier that should indicate the message in question.
+A `NULL` value for _msgid_ canbe used as well.
+
+Message identifiers can be used to assist in filtering logs.
+These should uniquely identify the nature of the problem, whe possible, to assist in trouble-shooting.
+They should also be short.
+Eight characters or less is ideal, and more than sixteen is strongly discouraged.
+
+The message is formatting as if by `sprintf`, using `msg` as the format, and remaining arguments as arguments to the format.
+
+The final function, `nng_log_auth`, is used for posting authentication related messages which might be treated specially, such as be storing them in a separate secured log file.
+It takes the severity as a level in _level_.
+The severity can be one of the following values:
+
+* `NNG_LOG_ERR`
+* `NNG_LOG_WARN`
+* `NNG_LOG_NOTICE`
+* `NNG_LOG_INFO`
+* `NNG_LOG_DEBUG`
+
+The message itself is handled according to the logging facility set up with xref:nng_mg_set_logger.3.adoc[`nng_log_set_logger`].
+Message delivery is best effort, and messages may be suppressed based on the priority set with xref:nng_log_set_level.3.adoc[`nng_log_set_level`].
+
+== SEE ALSO
+
+xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)],
+xref:nng_log_set_level.3.adoc[nng_log_set_level(3)],
+xref:nng_log_set_logger.3.adoc[nng_log_set_logger(3)]
diff --git a/docs/man/nng_log_set_facility.3.adoc b/docs/man/nng_log_set_facility.3.adoc
new file mode 100644
index 00000000..ecd6ab76
--- /dev/null
+++ b/docs/man/nng_log_set_facility.3.adoc
@@ -0,0 +1,47 @@
+= nng_log_set_facility(3)
+//
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_log_set_facility - set facility used for log messages
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+typedef enum nng_log_facility {
+	NNG_LOG_USER   = 1,
+	NNG_LOG_DAEMON = 3,
+	NNG_LOG_AUTH   = 10,
+	NNG_LOG_LOCAL0 = 16,
+	NNG_LOG_LOCAL1 = 17,
+	NNG_LOG_LOCAL2 = 18,
+	NNG_LOG_LOCAL3 = 19,
+	NNG_LOG_LOCAL4 = 20,
+	NNG_LOG_LOCAL5 = 21,
+	NNG_LOG_LOCAL6 = 22,
+	NNG_LOG_LOCAL7 = 23,
+} nng_log_facility;
+
+void nng_log_set_facility(nng_log_facility facility);
+----
+
+== DESCRIPTION
+
+The `nng_log_set_facility` is used to set the _facility_ of the application posting logs.
+This is used to assist with directing log content when handled by services such as `syslog`.
+
+Note that while the log levels used here overlap with common levels used by the syslog facility on POSIX systems, applications should not rely on this.
+
+== SEE ALSO
+
+xref:nng_log_set_level.3.adoc[nng_log_set_level(3)]
diff --git a/docs/man/nng_log_set_level.adoc b/docs/man/nng_log_set_level.adoc
new file mode 100644
index 00000000..012f93f8
--- /dev/null
+++ b/docs/man/nng_log_set_level.adoc
@@ -0,0 +1,42 @@
+= nng_log_set_level(3)
+//
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_log_set_level - set minimum level for logging messagse
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+typedef enum nng_log_level {
+	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
+	NNG_LOG_ERR    = 3,
+	NNG_LOG_WARN   = 4,
+	NNG_LOG_NOTICE = 5,
+	NNG_LOG_INFO   = 6,
+	NNG_LOG_DEBUG  = 7
+} nng_log_level;
+
+void nng_log_set_level(nng_log_level level);
+----
+
+== DESCRIPTION
+
+The `nng_log_set_level` function is used to set the minimum severity to _level_ for processing log messages.
+Any messages with a less severe rating are not processed and simply are discarded.
+Use `NNG_LOG_NONE` to suppress all log messages.
+Use `NNG_LOG_DEBUG` to receive all log messages.
+
+== SEE ALSO
+
+xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)]
diff --git a/docs/man/nng_log_set_logger.adoc b/docs/man/nng_log_set_logger.adoc
new file mode 100644
index 00000000..4f3cafc8
--- /dev/null
+++ b/docs/man/nng_log_set_logger.adoc
@@ -0,0 +1,52 @@
+= nng_log_set_logger(3)
+//
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_log_set_logger - set logging handler
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility,
+    const char *msgid, const char *msg);
+
+void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *);
+
+void nng_log_set_logger(nng_logger logger);
+----
+
+== DESCRIPTION
+
+The `nng_log_set_logger` is used to set the base logging function to _logger_.
+The _logger_ may be a user defined function to process log messages.
+Only a single logger may be registered at a time.
+If needed, the logger should make copies of either _msgid_ or _msg_, as those may not be valid once the logger function returns.
+
+The `nng_null_logger` function is an implementation of `nng_logger` that simply discards the content.
+
+The `nng_stderr_logger` function is an implementation that logs messages to the standard error stream.
+It will attempt to colorize messages by the severity, if the standard error is a terminal device.
+This can be supressed by setting either the `NO_COLOR` or `NNG_LOG_NO_COLOR` environment variables.
+
+The `nng_system_logger` attempts to use an appropriate system facility to log messages.
+For POSIX systems, this means using `syslog` to process the messages.
+For other the `nng_stderr_log` may be used as a fallback.
+
+== SEE ALSO
+
+xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)],
+xref:nng_log_set_level.3.adoc[nng_log_set_level(3)],
+xref:nng_log.3.adoc[nng_log(3)]