Organization changes abound.

1 files changed, 72 insertions, 0 deletions

diff --git a/docs/reference/src/tran/tcp.md b/docs/reference/src/tran/tcp.md
new file mode 100644
index 00000000..8085a978
--- /dev/null
+++ b/docs/reference/src/tran/tcp.md
@@ -0,0 +1,72 @@
+# TCP transport
+
+The {{i:*tcp* transport}}{{hi:*tcp*}} provides communication support between
+sockets across a {{i:TCP/IP}} network.
+
+Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it.
+
+## URI Format
+
+This transport uses URIs using the scheme {{i:`tcp://`}}, followed by
+an IP address or hostname, followed by a colon and finally a
+TCP {{i:port number}}.
+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 ({{i:`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 [`nng_sockaddr`][sockaddr] structure,
+the actual structure is either of type
+[`nng_sockaddr_in`][sockaddr_in] (for IPv4) or
+[`nng_sockaddr_in6`][sockaddr_in6] (for IPv6).
+
+## Transport Options
+
+The following transport options are supported by this transport,
+where supported by the underlying platform.
+
+- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR]
+- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR]
+- [`NNG_OPT_TCP_KEEPALIVE`][NNG_OPT_TCP_KEEPALIVE]
+- [`NNG_OPT_TCP_NODELAY`][NNG_OPT_TCP_NODELAY]
+- [`NNG_OPT_URL`][NNG_OPT_URL]
+
+{{#include ../refs.md}}