Add documentation for socket transport.

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

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

docs/man/nng_socket.7.adoc

@@ -0,0 +1,65 @@
+= nng_socket(7)
+//
+// Copyright 2023 Staysail Systems, Inc. <[email protected]>
+//
+// 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
+
+Not documented.
+
+=== 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.
+
+== 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_pipe.5.adoc[nng_pipe(5)],
+xref:nng_sockaddr.5.adoc[nng_sockaddr(5)],
+xref:nng.7.adoc[nng(7)]

docs/man/nng_socket_pair.3supp.adoc

@@ -0,0 +1,53 @@
+= nng_socket_pair(3)
+//
+// Copyright 2023 Staysail Systems, Inc. <[email protected]>
+//
+// 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)]