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