bsd socket transport

3 files changed, 63 insertions, 0 deletions

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}}