From 56507ab5c4db009be5251bde832f594fe5ed3d5e Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sun, 21 Apr 2024 12:23:07 -0700
Subject: 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.
---
 docs/man/nng_str_sockaddr.3.adoc | 52 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/man/nng_str_sockaddr.3.adoc

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

diff --git a/docs/man/nng_str_sockaddr.3.adoc b/docs/man/nng_str_sockaddr.3.adoc
new file mode 100644
index 00000000..03999d1a
--- /dev/null
+++ b/docs/man/nng_str_sockaddr.3.adoc
@@ -0,0 +1,52 @@
+= nng_str_sockaddr(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_str_sockaddr - get string representation of socket address
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+#define NNG_MAXADDRSTRLEN (NNG_MAXADDRLEN+16)
+const char *nng_str_sockaddr(const nng_sockaddr *sa, char *buf, size_t bufsz)
+----
+
+== DESCRIPTION
+
+The `nng_str_sockaddr()` is used to provide a displayable representation
+for the socket address _sa_.
+The content will be stored the location provided by _buf_, and will be
+formatted to fit within _bufsz_ bytes, truncating if necessary.
+
+As long as _bufsz_ is greater than zero, the result will be properly
+zero-terminated in the usual fashion.
+
+The `NNG_MAXADDRSTRLEN` can be used to provide a buffer large enough to hold most socket addresses.
+It is possible for applications to use very much larger socket addresses (using very long paths
+for IPC or inproc), but such addresses are not generally compatible with other implementations,
+and will be truncated here.
+
+== RETURN VALUES
+
+This function returns the _buf_ argument.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_sockaddr.5.adoc[nng_sockaddr(5)]
-- 
cgit v1.2.3-70-g09d2

