fixes #1746 Create a new socket:// transport for socketpair() based connections

This transport only listens, and creates connections when
the application calls setopt on the lister with NNG_OPT_SOCKET_FD,
to pass a file descriptor.  The FD is turned into an nng_stream,
and utilized for SP.  The protocol over the descriptor is identical
to the TCP protocol (not the IPC protocol).

The options for peer information are borrowed from the IPC transport,
as they may be useful for these purposes.

This includes a test suite and full documentation.

8 files changed, 205 insertions, 64 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index a33d4ee8..17d43c8e 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -302,6 +302,7 @@ if (NNG_ENABLE_DOC)
             nng_mtx_unlock
             nng_opts_parse
             nng_random
+            nng_socket_pair
             nng_thread_create
             nng_thread_destroy
             nng_thread_set_name
@@ -388,6 +389,7 @@ if (NNG_ENABLE_DOC)
             nng_rep
             nng_req
             nng_respondent
+            nng_socket
             nng_sub
             nng_surveyor
             nng_tcp
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 6f64de41..c9df9c0d 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -305,6 +305,7 @@ as a convenience to aid in creating portable applications.
 |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex
 |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options
 |xref:nng_random.3supp.adoc[nng_random()]|get random number
+|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets
 |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread
 |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread
 |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name
diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc
index 1097a5f8..c0e1a640 100644
--- a/docs/man/nng.7.adoc
+++ b/docs/man/nng.7.adoc
@@ -69,6 +69,7 @@ xref:nng_surveyor.7.adoc[nng_surveyor(7)]:: Surveyor side of survey protocol
 [horizontal]
 xref:nng_inproc.7.adoc[nng_inproc(7)]:: Intra-process transport
 xref:nng_ipc.7.adoc[nng_ipc(7)]:: Inter-process transport
+xref:nng_socket.7.adoc[nng_socket(7)]:: BSD socket transport
 xref:nng_tls.7.adoc[nng_tls(7)]:: TLSv1.2 over TCP transport
 xref:nng_tcp.7.adoc[nng_tcp(7)]:: TCP (and TCPv6) transport
 xref:nng_ws.7.adoc[nng_ws(7)]:: WebSocket transport
diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc
index 856a00ac..c085e4d2 100644
--- a/docs/man/nng_ipc.7.adoc
+++ b/docs/man/nng_ipc.7.adoc
@@ -1,6 +1,6 @@
 = nng_ipc(7)
 //
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -107,14 +107,14 @@ except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_so
 The following transport options are supported by this transport,
 where supported by the underlying platform.
 
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_GID[`NNG_OPT_IPC_PEER_GID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_PID[`NNG_OPT_IPC_PEER_PID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_UID[`NNG_OPT_IPC_PEER_UID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_ZONEID[`NNG_OPT_IPC_PEER_ZONEID`]
 * xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PERMISSIONS[`NNG_OPT_IPC_PERMISSIONS`]
 * xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_SECURITY_DESCRIPTOR[`NNG_OPT_IPC_SECURITY_DESCRIPTOR`]
 * xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
 * xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`]
 * xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`]
 
 == SEE ALSO
diff --git a/docs/man/nng_ipc_options.5.adoc b/docs/man/nng_ipc_options.5.adoc
index 72f383ea..516fbe80 100644
--- a/docs/man/nng_ipc_options.5.adoc
+++ b/docs/man/nng_ipc_options.5.adoc
@@ -1,6 +1,6 @@
 = nng_ipc_options(5)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2019 Devolutions <info@devolutions.net>
 //
@@ -43,43 +43,9 @@ have other access restrictions.
 An attempt has been made to include details about such restrictions in the
 description of the option.
 
-NOTE: The availability of any of the following options is platform-specific,
+NOTE: The availability of the following options is platform-specific,
 as the implementations of IPC are quite different on Windows and POSIX systems.
 
-=== IPC Options
-
-[[NNG_OPT_IPC_PEER_GID]]((`NNG_OPT_IPC_PEER_GID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's primary
-group id.
-This is the effective group id of the peer when either the underlying
-`listen()` or `connect()` calls were made, and is not forgeable.
-This option is generally only available on POSIX systems.
-
-[[NNG_OPT_IPC_PEER_PID]]((`NNG_OPT_IPC_PEER_PID`))::
-(`uint64_t`)
-This read-only option provides the the process id
-of the connected peer.
-This option is only available on Windows, Linux, and certain other systems.
-+
-NOTE: Applications should not assume that the process ID does not change,
-as it is possible (although unsupported!) for a nefarious process to pass a
-file descriptor between processes.
-However, it is not possible for a nefarious application to forge the identity
-of a well-behaved one using this method.
-
-[[NNG_OPT_IPC_PEER_UID]]((`NNG_OPT_IPC_PEER_UID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's user id.
-This is the effective user id of the peer when either the underlying
-`listen()` or `connect()` calls were made, and is not forgeable.
-This option is generally only available on POSIX systems.
-
-[[NNG_OPT_IPC_PEER_ZONEID]]((`NNG_OPT_IPC_PEER_ZONEID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's the zone id.
-Zones (and this option) are only supported on Solaris and illumos systems.
-
 [[NNG_OPT_IPC_PERMISSIONS]]((`NNG_OPT_IPC_PERMISSIONS`))::
 (`int`)
 This write-only option may be applied to a listener to configure the
@@ -115,10 +81,18 @@ named pipe.
 The value is a pointer, `PSECURITY_DESCRIPTOR`, and may only be
 applied to listeners that have not been started yet.
 
+=== Common Platform Specific Options
+
+The following options are supported by this transport when the underlying platform supports them:
+
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`] (also available as `NNG_OPT_IPC_PEER_GID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`] (also available as `NNG_OPT_IPC_PEER_PID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`] (also available as `NNG_OPT_IPC_PEER_UID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`] (also available as `NNG_OPT_IPC_PEER_ZONEID`)
+
 === Inherited Options
 
-Generally, the following option values are also available for TLS objects,
-when appropriate for the context:
+Generally, the following option values are also available when appropriate for the context:
 
 * xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
 * xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
@@ -126,11 +100,11 @@ when appropriate for the context:
 == SEE ALSO
 
 [.text-left]
-xref:nng_ipc_dialer_getopt.3ipc.adoc[nng_ipc_dialer_getopt(3ipc)],
-xref:nng_ipc_dialer_setopt.3ipc.adoc[nng_ipc_dialer_setopt(3ipc)],
-xref:nng_ipc_getopt.3ipc.adoc[nng_ipc_getopt(3ipc)],
-xref:nng_ipc_listener_getopt.3ipc.adoc[nng_ipc_listener_getopt(3ipc)],
-xref:nng_ipc_listener_setopt.3ipc.adoc[nng_ipc_listener_setopt(3ipc)],
-xref:nng_ipc_setopt.3ipc.adoc[nng_ipc_setopt(3ipc)],
+xref:nng_dialer_get.3.adoc[nng_dialer_get(3)],
+xref:nng_dialer_set.3.adoc[nng_dialer_set(3)],
+xref:nng_listener_get.3.adoc[nng_listener_get(3)],
+xref:nng_listener_set.3.adoc[nng_listener_set(3)],
+xref:nng_pipe_get.3.adoc[nng_pipe_get(3)],
 xref:nng_options.5.adoc[nng_options(5)]
-xref:nng.7.adoc[nng(7)]
+xref:nng.7.adoc[nng(7)],
+xref:nng_ipc.7.adoc[nng_ipc(7)]
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index e4e5124d..dd971f9f 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -1,6 +1,6 @@
 = nng_options(5)
 //
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2019 Devolutions <info@devolutions.net>
 //
@@ -39,6 +39,10 @@ nng_options - socket, dialer, listener, and pipe options
 #define NNG_OPT_RECVMAXSZ     "recv-size-max"
 #define NNG_OPT_RECONNMINT    "reconnect-time-min"
 #define NNG_OPT_RECONNMAXT    "reconnect-time-max"
+#define NNG_OPT_PEER_GID      "ipc:peer-gid"
+#define NNG_OPT_PEER_PID      "ipc:peer-pid"
+#define NNG_OPT_PEER_UID      "ipc:peer-uid"
+#define NNG_OPT_PEER_ZONEID   "ipc:peer-zoneid"
 ----
 
 == DESCRIPTION
@@ -328,27 +332,59 @@ This read-only option is used to obtain the 16-bit number for the socket's proto
 This read-only option is used to obtain the 16-bit number of the
 peer protocol for the socket.
 
-[[NNG_OPT_PROTONAME]]
-((`NNG_OPT_PROTONAME`))::
-(string)
-This read-only option is used to obtain the name of the socket's protocol.
+[[NNG_OPT_PEER_GID]]
+((`NNG_OPT_PEER_GID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's primary group id, when known.
+This is the effective group id of the peer when either the underlying
+`listen()` or `connect()` calls were made, and is not forgeable.
+This option is generally only available on POSIX systems, only on certain transports.
+
+[[NNG_OPT_PEER_PID]]
+((`NNG_OPT_PEER_PID`))::
+(`uint64_t`)
+This read-only option provides the process id of the connected peer, when known.
+This option is only available on certain platforms and transports.
++
+NOTE: Applications should not assume that the process ID does not change,
+as it may be possible for a process to pass a file descriptor between processes.
+However, it is not possible for a nefarious application to forge the identity
+of a well-behaved one using this method.
+
+[[NNG_OPT_PEER_UID]]
+((`NNG_OPT_PEER_UID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's user id.
+This is the effective user id of the peer when either the underlying
+`listen()` or `connect()` calls were made, and cannot be forged.
+This option is generally only available on POSIX systems, on certain transports.
+
+[[NNG_OPT_PEER_ZONEID]]
+((`NNG_OPT_PEER_ZONEID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's the zone id.
+Zones (and this option) are only supported on Solaris and illumos systems, on select transports.
 
 [[NNG_OPT_PEERNAME]]
 ((`NNG_OPT_PEERNAME`))::
 (string)
-This read-only option is used to obtain the name of the peer protocol for
-the socket.
+This read-only option is used to obtain the name of the peer protocol for the socket.
+
+[[NNG_OPT_PROTONAME]]
+((`NNG_OPT_PROTONAME`))::
+(string)
+This read-only option is used to obtain the name of the socket's protocol.
 
 == SEE ALSO
 
 [.text-left]
-xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)],
-xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)],
-xref:nng_getopt.3.adoc[nng_getopt(3)],
-xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
-xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)],
-xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
-xref:nng_setopt.3.adoc[nng_setopt(3)],
+xref:nng_dialer_get.3.adoc[nng_dialer_get(3)],
+xref:nng_dialer_set.3.adoc[nng_dialer_set(3)],
+xref:nng_listener_get.3.adoc[nng_listener_get(3)],
+xref:nng_listener_set.3.adoc[nng_listener_set(3)],
+xref:nng_pipe_get.3.adoc[nng_pipe_get(3)],
+xref:nng_socket_get.3.adoc[nng_socket_get(3)],
+xref:nng_socket_set.3.adoc[nng_socket_set(3)],
 xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
 xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
 xref:nng_tls_options.5.adoc[nng_tls_options(5)],
diff --git a/docs/man/nng_socket.7.adoc b/docs/man/nng_socket.7.adoc
new file mode 100644
index 00000000..f575eed7
--- /dev/null
+++ b/docs/man/nng_socket.7.adoc
@@ -0,0 +1,74 @@
+= nng_socket(7)
+//
+// Copyright 2023 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 - BSD Socket transport (experimental)
+
+== DESCRIPTION
+
+(((BSD Socket)))(((transport, _socket_)))
+The ((_socket_ transport)) provides communication support between
+peers across a arbitrary BSD sockets, such as those that are
+created with xref:nng_socket_pair.3supp.adoc[`nng_socket_pair()`].
+
+This transport only supports xref:nng_listener.5.adoc[listeners], using xref:nng_listener_create.3.adoc[`nng_listener_create()`].
+
+NOTE: Attempts to create a xref:nng_dialer.5.adoc[dialer] using this transport will result in `NNG_ENOTSUP`.
+
+The socket file descriptor is passed to the listener using the `NNG_OPT_SOCKET_FD` option (as an integer).
+Setting this option (which is read-only and can be set multiple times) will cause the listener
+to create a xref:nng_pipe.5.adoc[pipe] associated backed by the file descriptor.
+
+The protocol between peers using this pipe is at present compatible with the protocol used for the
+xref:nng_tcp.7.adoc[TCP] transport, but this is an implementation detail and subject to change without notice.
+
+NOTE: This transport is *experimental*, and at present is only supported on POSIX platforms.
+
+=== Registration
+
+No special action is necessary to register this transport.
+
+=== URI Format
+
+(((URI, `socket://`)))
+This transport uses the URL `socket://`, without further qualification.
+
+=== Socket Address
+
+The socket address will be of family `NNG_AF_UNSPEC`.
+There are no further socket details available.
+
+=== Transport Options
+
+The following transport option is available:
+
+((`NNG_OPT_SOCKET_FD`))::
+
+(int) This is a write-only option, that may be set multiple times on a listener.
+The listener will create a pipe backed by the given file descriptor passed as an argument.
+
+Additionally, the following options may be supported on pipes when the platform supports them:
+
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`]
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket_pair.3supp.adoc[nng_socket_pair(3)],
+xref:nng_dialer.5.adoc[nng_dialer(5)],
+xref:nng_listener.5.adoc[nng_listener(5)],
+xref:nng_options.5.adoc[nng_options(5)],
+xref:nng_pipe.5.adoc[nng_pipe(5)],
+xref:nng_sockaddr.5.adoc[nng_sockaddr(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc
new file mode 100644
index 00000000..063c9f0b
--- /dev/null
+++ b/docs/man/nng_socket_pair.3supp.adoc
@@ -0,0 +1,53 @@
+= nng_socket_pair(3)
+//
+// Copyright 2023 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_pair - create a connected pair of BSD sockets
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+int nng_socket_pair(int fds[2]);
+----
+
+== DESCRIPTION
+
+The `nng_socket_pair()` function creates a pair of connected BSD sockets.
+These sockets, which are returned in the _fds_ array, are suitable for
+use with the xref:nng_socket.7.adoc[_socket_] transport.
+
+On POSIX platforms, this is a thin wrapper around the standard `socketpair()` function,
+using the `AF_UNIX` family and the `SOCK_STREAM` socket type.
+
+NOTE: At present only POSIX platforms implementing `socketpair()` are supported with this function.
+
+TIP: This function may be useful for creating a shared connection between a parent process and
+a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ENOMEM`:: Insufficient memory exists.
+`NNG_ENOTSUP`:: This platform does not support socket pairs.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.7.adoc[nng_socket(7)],
+xref:nng.7.adoc[nng(7)]