From df371e0a77e5b30f5ebddd0902fc8dd46b349849 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sat, 13 Apr 2024 10:59:05 -0700
Subject: fixes #543 Add logging support framework

---
 docs/man/nng_log.3.adoc | 62 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/man/nng_log.3.adoc

(limited to 'docs/man/nng_log.3.adoc')

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)]
-- 
cgit v1.2.3-70-g09d2

