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, 74 insertions, 0 deletions

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