bsd socket transport

5 files changed, 63 insertions, 184 deletions

diff --git a/docs/man/nng_socket.7.adoc b/docs/man/nng_socket.7.adoc
deleted file mode 100644
index a7d40296..00000000
--- a/docs/man/nng_socket.7.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-= nng_socket(7)
-//
-// 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 - BSD Socket transport (experimental)
-
-== DESCRIPTION
-
-(((BSD Socket)))(((transport, _socket_)))
-The ((_socket_ transport)) supports communication between
-peers across 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 xref:nng_dialer.5.adoc[dialers] 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 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 transport is 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.
-Each time this is set, the listener will create a xref:nng_pipe.5.adoc[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_tcp.7.adoc b/docs/man/nng_tcp.7.adoc
deleted file mode 100644
index c1b9a439..00000000
--- a/docs/man/nng_tcp.7.adoc
+++ /dev/null
@@ -1,110 +0,0 @@
-= nng_tcp(7)
-//
-// Copyright 2019 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
-// 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_tcp - TCP/IP transport
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/transport/tcp/tcp.h>
-
-int nng_tcp_register(void);
-----
-
-== DESCRIPTION
-
-(((transport, _tcp_)))
-The ((_tcp_ transport)) provides communication support between
-sockets across a ((TCP/IP)) network.
-Both IPv4 and IPv6 are supported when the underlying platform also supports it.
-
-// We need to insert a reference to the nanomsg RFC.
-
-=== Registration
-
-This transport is generally built-in to the core of _NNG_, so
-no extra steps to use it should be necessary.
-
-=== URI Format
-
-(((URI, `tcp://`)))
-This transport uses URIs using the scheme `tcp://`, followed by
-an IP address or hostname, followed by a colon and finally a
-TCP port number.(((port number, TCP)))
-For example, to contact port 80 on the localhost either of the following URIs
-could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`.
-
-A URI may be restricted to IPv6 using the scheme `tcp6://`, and may
-be restricted to IPv4 using the scheme `tcp4://`.
-
-NOTE: Specifying `tcp6://` may not prevent IPv4 hosts from being used with
-IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
-listeners.
-The details of this varies across operating systems.
-
-NOTE: Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not
-be understood by other implementations.
-
-TIP: We recommend using either numeric IP addresses, or names that are
-specific to either IPv4 or IPv6 to prevent confusion and surprises.
-
-When specifying IPv6 addresses, the address must be enclosed in
-square brackets (`[]`) to avoid confusion with the final colon
-separating the port.
-
-For example, the same port 80 on the IPv6 loopback address (`::1`) would
-be specified as `tcp://[::1]:80`.
-
-The special value of 0 (`INADDR_ANY`)(((`INADDR_ANY`)))
-can be used for a listener to indicate that it should listen on all
-interfaces on the host.
-A short-hand for this form is to either omit the address, or specify
-the asterisk (`*`) character.
-For example, the following three URIs are all equivalent,
-and could be used to listen to port 9999 on the host:
-
-  1. `tcp://0.0.0.0:9999`
-  2. `tcp://*:9999`
-  3. `tcp://:9999`
-
-The entire URI must be less than `NNG_MAXADDRLEN` bytes long.
-
-=== Socket Address
-
-When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure,
-the actual structure is either of type
-xref:nng_sockaddr_in.5.adoc[`nng_sockaddr_in`] (for IPv4) or
-xref:nng_sockaddr_in6.5.adoc[`nng_sockaddr_in6`] (for IPv6).
-
-=== Transport Options
-
-The following transport options are supported by this transport,
-where supported by the underlying platform.
-
-* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
-* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
-* xref:nng_tcp_options.5.adoc#NNG_OPT_TCP_KEEPALIVE[`NNG_OPT_TCP_KEEPALIVE`]
-* xref:nng_tcp_options.5.adoc#NNG_OPT_TCP_NODELAY[`NNG_OPT_TCP_NODELAY`]
-* xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`]
-
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_sockaddr.5.adoc[nng_sockaddr(5)],
-xref:nng_sockaddr_in.5.adoc[nng_sockaddr_in(5)],
-xref:nng_sockaddr_in6.5.adoc[nng_sockaddr_in6(5)],
-xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index e81fec99..e8d40df8 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -22,6 +22,7 @@
   - [IPC](tran/ipc.md)
   - [INPROC](tran/inproc.md)
   - [TCP](tran/tcp.md)
+  - [SOCKET](tran/socket.md)
 
 - [API Reference](./api/index.md)
 
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index 5d808e0b..43e9b435 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -6,6 +6,8 @@
 [duration]: ../overview/duration.md
 [msg]: ../msg/index.md
 [pipe]: ../overview/pipe.md
+[dialer]: ../overview/dialer.md
+[listener]: ../overview/listener.md
 [socket]: ../sock/index.md
 [sockaddr]: ../overview/sockaddr.md
 [sockaddr_in]: ../overview/sockaddr_in.md
@@ -158,6 +160,7 @@
 [NNG_OPT_PEER_UID]: ../opts/ipc_options.md
 [NNG_OPT_PEER_ZONEID]: ../opts/ipc_options.md
 [NNG_OPT_URL]: ../api/nng_options.md#NNG_OPT_URL
+[NNG_OPT_SOCKET_FD]: ../opts/sock_options.md
 
 <!-- External -->
 
diff --git a/docs/reference/src/tran/socket.md b/docs/reference/src/tran/socket.md
new file mode 100644
index 00000000..61de130c
--- /dev/null
+++ b/docs/reference/src/tran/socket.md
@@ -0,0 +1,59 @@
+BSD Socket transport (experimental)
+
+The {{i:_socket_ transport}} supports communication between
+peers across arbitrary BSD sockets, such as those that are
+created with [`nng_socket_pair()`][nng_socket_pair].
+
+This transport only supports [listeners][listener],
+using [`nng_listener_create()`][nng_listener_create].
+
+> [!NOTE]
+> Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`.
+
+The socket file descriptor is passed to the listener using
+the [{{i:`NNG_OPT_SOCKET_FD`}}][NNG_OPT_SOCKET_FD] option (as an integer).
+Setting this option will cause the listener to create a [pipe][pipe]
+backed by the file descriptor.
+
+The protocol between peers using this transport is compatible with the protocol used
+for the [_tcp_][tcp] transport, but this is an implementation detail and subject to change without notice.[^1]
+
+[^1]: Specifically it is not compatible with the [_ipc_][ipc] transport.
+
+> [!NOTE]
+> This transport is _experimental_, and at present is only supported on POSIX platforms.[^2]
+
+[^2]: Windows lacks a suitable `socketpair()` equivalent function we could use.
+
+### Registration
+
+No special action is necessary to register this transport.
+
+### URI Format
+
+This transport uses the URL {{i:`socket://`}}, without further qualification.
+
+### Socket Address
+
+The socket address will be of family {{i:`NNG_AF_UNSPEC`}}.
+There are no further socket details available.
+
+### Transport Options
+
+The following transport option is available:
+
+- {{i:`NNG_OPT_SOCKET_FD`}}: \
+  (int) \
+  \
+  This is a write-only option, that may be set multiple times on a listener.
+  Each time this is set, the listener will create a [pipe][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:
+
+- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID]
+- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID]
+- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID]
+- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID]
+
+{{#include ../refs.md}}