Add new functions for socket identity.

These functions were added in the main branch for NNG 2.0, and
we add them here to facilitate converting any code that happened
to use the options (`NNG_OPT_PROTO`, `NNG_OPT_PROTONAME`,
`NNG_OPT_PEER`, `NNG_OPT_PEERNAME`, and `NNG_OPT_RAW`.

Its unlikely that many applications need this, but providing these
as a transition aid may help applications start adopting new APIs now.

6 files changed, 155 insertions, 0 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index 6db3318f..f9d03a19 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -165,6 +165,9 @@ if (NNG_ENABLE_DOC)
             nng_sleep_aio
             nng_socket_id
             nng_socket_get
+            nng_socket_proto_id
+            nng_socket_proto_name
+            nng_socket_raw
             nng_socket_set
             nng_stats_free
             nng_stats_get
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 8d006ba8..f1e14ac4 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -53,6 +53,9 @@ The following functions operate on sockets.
 |xref:nng_setopt.3.adoc[nng_setopt()]|set socket option
 |xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option
 |xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier
+|xref:nng_socket_raw.3.adoc[nng_socket_raw()]|is the socket raw
+|xref:nng_socket_proto_id.3.adoc[nng_socket_raw()]|get the socket protocol identifier
+|xref:nng_socket_proto_name.3.adoc[nng_socket_raw()]|get the socket protocol name
 |xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option
 |===
 
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index 94da37a0..7bf2a03b 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -113,6 +113,8 @@ automatically copy message headers from a received message to the corresponding
 reply, whereas in raw mode this is not done.)
 See xref:nng.7.adoc#raw_mode[Raw Mode] for more details.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_raw.3.adoc[`nng_socket_raw`] function instead.
+
 [[NNG_OPT_RECONNMINT]]
 ((`NNG_OPT_RECONNMINT`))::
 (((reconnect time, minimum)))
@@ -326,12 +328,16 @@ application.
 (`int`)
 This read-only option is used to obtain the 16-bit number for the socket's protocol.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_id.3.adoc[`nng_socket_proto_id`] function instead.
+
 [[NNG_OPT_PEER]]
 ((`NNG_OPT_PEER`))::
 (`int`)
 This read-only option is used to obtain the 16-bit number of the
 peer protocol for the socket.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_id.3.adoc[`nng_socket_peer_id`] function instead.
+
 [[NNG_OPT_PEER_GID]]
 ((`NNG_OPT_PEER_GID`))::
 (`uint64_t`)
@@ -370,11 +376,15 @@ Zones (and this option) are only supported on Solaris and illumos systems, on se
 (string)
 This read-only option is used to obtain the name of the peer protocol for the socket.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_name.3.adoc[`nng_socket_peer_name`] function instead.
+
 [[NNG_OPT_PROTONAME]]
 ((`NNG_OPT_PROTONAME`))::
 (string)
 This read-only option is used to obtain the name of the socket's protocol.
 
+NOTE: This option is deprecated.  Use the xref:nng_socket_proto_name.3.adoc[`nng_socket_proto_name`] function instead.
+
 == SEE ALSO
 
 [.text-left]
diff --git a/docs/man/nng_socket_proto_id.3.adoc b/docs/man/nng_socket_proto_id.3.adoc
new file mode 100644
index 00000000..95d9dbee
--- /dev/null
+++ b/docs/man/nng_socket_proto_id.3.adoc
@@ -0,0 +1,46 @@
+= nng_socket_proto_id(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_socket_proto_id - obtain the socket protocol id
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_proto_id(nng_socket s, uint16_t *id);
+int nng_socket_peer_id(nng_socket s, uint16_t *id);
+----
+
+== DESCRIPTION
+
+These functions store the 16-bit protocol identifier of either the socket _s_,
+or its natural peer, in _id_.
+
+TIP: These functions should be used in place of the `NNG_OPT_PROTO` and `NNG_OPT_PEER`
+options in new code.
+
+== RETURN VALUES
+
+These functions return zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_socket_proto_name.3.adoc b/docs/man/nng_socket_proto_name.3.adoc
new file mode 100644
index 00000000..da2f565f
--- /dev/null
+++ b/docs/man/nng_socket_proto_name.3.adoc
@@ -0,0 +1,49 @@
+= nng_socket_proto_name(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_socket_proto_name - obtain the socket protocol name
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_proto_name(nng_socket s, const char **name);
+int nng_socket_peer_name(nng_socket s, const char **name);
+----
+
+== DESCRIPTION
+
+These functions store the protocol name of either the socket _s_,
+or its natural peer, in _name.
+
+NOTE: The string value obtained by these functions is statically stored
+as part of the program text, and must not be freed or modified.
+
+TIP: These functions should be used in place of the `NNG_OPT_PROTONAME` and `NNG_OPT_PEERNAME`
+options in new code.
+
+== RETURN VALUES
+
+These functions return zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_socket_raw.3.adoc b/docs/man/nng_socket_raw.3.adoc
new file mode 100644
index 00000000..594843b9
--- /dev/null
+++ b/docs/man/nng_socket_raw.3.adoc
@@ -0,0 +1,44 @@
+= nng_socket_raw(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_socket_raw - return whether socket is cooked or raw
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_socket_raw(nng_socket s, bool *raw);
+----
+
+== DESCRIPTION
+
+The `nng_socket_raw()` function stores `true` in _raw_ if the socket is in raw mode,
+otherwise it stores `false`.
+
+TIP: This function should be used in place of the `NNG_OPT_RAW` option in new code.
+
+== RETURN VALUES
+
+This function returns zero on success, or an error if the socket is invalid.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng.7.adoc[nng(7)]