Logging improvements (#1816)

* Add nng_str_sockaddr to get string representation of socket address.

* Added nng_log_get_level() is meant to allow users to obtain the
current level and avoid some possibly expensive operations just
to collect debugging information when debugging is not in effect.

We use a custom logger for NUTS, and this fits within the NUTS
test framework well, so that if -v is supplied we get more content.
All tests now get this by default.

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/man/nng_log_set_logger.3.adoc b/docs/man/nng_log_set_logger.3.adoc
new file mode 100644
index 00000000..eedbca49
--- /dev/null
+++ b/docs/man/nng_log_set_logger.3.adoc
@@ -0,0 +1,53 @@
+= 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.
+This is the default logger, so logging is disabled by default.
+
+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)]