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.

1 files changed, 53 insertions, 0 deletions

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)]