docs: converted and improved stream factory docs

17 files changed, 329 insertions, 1096 deletions

diff --git a/docs/man/nng_stream_dialer.5.adoc b/docs/man/nng_stream_dialer.5.adoc
deleted file mode 100644
index eef23a3d..00000000
--- a/docs/man/nng_stream_dialer.5.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= nng_stream_dialer(5)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer - byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stream_dialer nng_stream_dialer;
-----
-
-== DESCRIPTION
-
-(((byte stream, dialer)))
-An `nng_stream_dialer` is a handle to a dialer for byte streams,
-and is responsible for creating
-xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte
-streams) by connecting to remote peers.
-
-NOTE: The `nng_stream_dialer` object is used for low-level byte stream
-connections, and should not be confused with a high-level
-xref:nng_dialer.5.adoc[`nng_dialer`] object.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)],
-xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)],
-xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)],
-xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)],
-xref:nng_stream.5.adoc[nng_stream(5)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_dialer_alloc.3str.adoc b/docs/man/nng_stream_dialer_alloc.3str.adoc
deleted file mode 100644
index 0c2db67c..00000000
--- a/docs/man/nng_stream_dialer_alloc.3str.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-= nng_stream_dialer_alloc(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer_alloc - allocate byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_dialer_alloc(nng_stream_dialer **dp, const char *addr);
-
-int nng_stream_dialer_alloc_url(nng_stream_dialer **dp, const nng_url *url);
-----
-
-== DESCRIPTION
-
-These functions allocates a dialer for byte streams.
-Dialers create
-xref:nng_stream.5.adoc[`nng_stream`] objects by initiating outgoing
-connections, via the
-xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] function.
-
-The first form, `nng_stream_dialer_alloc()`, connects to the address
-specified by _addr_, which should be a string representing a URL.
-
-The second form, `nng_stream_dialer_alloc_url()`, takes a pre-parsed
-or pre-constructed
-xref:nng_url.5.adoc[`nng_url`] object to determine the remote address.
-
-These functions may support different URL schemes, such as
-`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`.
-
-Both forms store the dialer in the location referenced by _dp_.
-
-== RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists.
-`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation.
-`NNG_EADDRINVAL`:: The URL requested is invalid.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)]
-xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)]
-xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)]
-xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)]
-xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)]
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_dialer_close.3str.adoc b/docs/man/nng_stream_dialer_close.3str.adoc
deleted file mode 100644
index 59d9dec0..00000000
--- a/docs/man/nng_stream_dialer_close.3str.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= nng_stream_dialer_close(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer_close - close byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_dialer_close(nng_stream_dialer *d);
-----
-
-== DESCRIPTION
-
-The `nng_stream_dialer_close()` function closes the supplied byte stream
-dialer _d_,
-but does not free the underlying resources associated with it.
-
-If any
-xref:nng_stream_dialer_dial.3str.adoc[dial]
-operations using _d_ are
-in progress, they will be terminated with an `NNG_ECLOSED` error condition.
-
-Furthermore any future accesses to the dialer _d_ will also result in
-`NNG_ECLOSED`.
-
-NOTE: This function does not release the memory for the dialer, so the
-application should still free the memory using
-xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`]
-once it is certain that nothing else is using it.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)],
-xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)],
-xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_dialer_dial.3str.adoc b/docs/man/nng_stream_dialer_dial.3str.adoc
deleted file mode 100644
index 8dcd4ec2..00000000
--- a/docs/man/nng_stream_dialer_dial.3str.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-= nng_stream_dialer_dial(3str)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer_dial - initiate outgoing byte stream connection
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_dialer_dial(nng_stream_dialer *d, nng_aio *aio);
-----
-
-== DESCRIPTION
-
-The `nng_stream_dialer_dial()` attempts to establish a connection to the
-remote peer for the dialer _d_.
-The operation is completed asynchronously, using _aio_.
-
-TIP: The peer address is determined by the address specified using
-xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc()`] or 
-xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc_url()`].
-
-If a connection is successfully established, the _aio_ will have the
-resulting
-xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output.
-(See
-xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].)
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-[horizontal]
-`NNG_EADDRINVAL`:: The address specified is invalid.
-`NNG_ECANCELED`:: The operation was aborted.
-`NNG_ECLOSED`:: The dialer is closed.
-`NNG_ECONNREFUSED`:: The connection was refused by the server.
-`NNG_ECONNRESET`:: The connection was reset by the server.
-`NNG_ENOMEM`:: Insufficient free memory exists.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)],
-xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)],
-xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_stream.5.adoc[nng_stream(5)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_dialer_free.3str.adoc b/docs/man/nng_stream_dialer_free.3str.adoc
deleted file mode 100644
index 6669ca1e..00000000
--- a/docs/man/nng_stream_dialer_free.3str.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= nng_stream_dialer_free(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-
-// 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_stream_dialer_free - free byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_dialer_free(nng_stream_dialer *d);
-----
-
-== DESCRIPTION
-
-The `nng_stream_dialer_free()` function closes the supplied
-byte stream dialer _d_,
-and frees the underlying resources associated with it.
-
-If any
-xref:nng_stream_dialer_dial.3str.adoc[dial] operations using _d_ are
-in progress, they will be terminated with an `NNG_ECLOSED` error condition.
-
-WARNING: It is important that the application ensure that no further accesses
-are made to _d_, as the memory backing it will be reclaimed for other uses.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)],
-xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)],
-xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_dialer_get.3str.adoc b/docs/man/nng_stream_dialer_get.3str.adoc
deleted file mode 100644
index aece5521..00000000
--- a/docs/man/nng_stream_dialer_get.3str.adoc
+++ /dev/null
@@ -1,109 +0,0 @@
-= nng_stream_dialer_get(3str)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer_get - get option from byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp);
-
-int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp);
-
-int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp);
-
-int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp);
-
-int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp);
-
-int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp);
-
-int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp);
-----
-
-== DESCRIPTION
-
-
-The `nng_stream_dialer_get()` functions are used to retrieve option values for the
-xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_.
-
-The actual options that may be retrieved in this way vary.
-A number of them are documented in
-xref:nng_options.5.adoc[nng_options(5)] and additional linked documents.
-
-=== Forms
-
-In all of these forms, the option _opt_ is retrieved from the connected
-byte stream dialer _d_.
-The forms vary based on the type of the option they take.
-
-The details of the type, size, and semantics of the option will depend
-on the actual option, and will be documented with the option itself.
-
-`nng_stream_dialer_get_bool()`::
-This function is for options which take a Boolean (`bool`).
-
-`nng_stream_dialer_get_int()`::
-This function is for options which take an integer (`int`).
-
-`nng_stream_dialer_get_ms()`::
-This function is used to retrieve time
-xref:nng_duration.5.adoc[durations]
-(such as timeouts), stored as a number of milliseconds.
-(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and
-the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.)
-
-`nng_stream_dialer_get_size()`::
-This function is used to retrieve a size,
-typically for buffer sizes, message maximum sizes, and similar options.
-
-`nng_stream_dialer_get_addr()`::
-This function is used to retrieve a
-xref:nng_sockaddr.5.adoc[socket address].
-
-`nng_stream_dialer_get_string()`::
-This function is used to retrieve a `NULL`-terminated string.
-This string is created from the source using
-xref:nng_strdup.3.adoc[`nng_strdup()`]
-and consequently must be freed by the caller using
-xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed.
-
-`nng_stream_dialer_get_uint64()`::
-This function is used to retrieve a 64-bit unsigned value.
-This is typically used for identifiers, network
-numbers, and similar options.
-
-== RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The dialer is closed.
-`NNG_EINVAL`:: There was insufficient space to receive the object.
-	The amount of data actually needed is returned in _sizep_.
-`NNG_ENOTSUP`:: The option is not supported.
-`NNG_EWRITEONLY`:: The option may not read.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)],
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_dialer_set.3str.adoc b/docs/man/nng_stream_dialer_set.3str.adoc
deleted file mode 100644
index 2c75c9d9..00000000
--- a/docs/man/nng_stream_dialer_set.3str.adoc
+++ /dev/null
@@ -1,111 +0,0 @@
-= nng_stream_dialer_set(3str)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_dialer_set - set option on byte stream dialer
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_dialer_set_bool(nng_stream_dialer *d, const char *opt, bool val);
-
-int nng_stream_dialer_set_int(nng_stream_dialer *d, const char *opt, int val);
-
-int nng_stream_dialer_set_ms(nng_stream_dialer *d, const char *opt, nng_duration val);
-
-int nng_stream_dialer_set_size(nng_stream_dialer *d, const char *opt, size_t val);
-
-int nng_stream_dialer_set_string(nng_stream_dialer *d, const char *opt, const char *val);
-
-int nng_stream_dialer_set_uint64(nng_stream_dialer *d, const char *opt, uint64_t val);
-
-int nng_stream_dialer_set_addr(nng_stream_dialer *d, const char *opt, const nng_sockaddr *val);
-
-----
-
-== DESCRIPTION
-
-The `nng_stream_dialer_set` functions are used to configure options for the
-xref:nng_stream.5.adoc[byte stream dialer] _d_.
-The actual options that may be configured in this way vary, and are
-specified by _opt_.
-A number of them are documented in
-xref:nng_options.5.adoc[nng_options(5)].
-
-Additionally some transport-specific and protocol-specific options are
-documented with the transports and protocols themselves.
-
-=== Forms
-
-The details of the type, size, and semantics of the option will depend
-on the actual option, and will be documented with the option itself.
-
-`nng_stream_dialer_set_bool()`::
-This function is for options which take a Boolean (`bool`).
-
-`nng_stream_dialer_set_int()`::
-This function is for options which take an integer (`int`).
-
-`nng_stream_dialer_set_ms()`::
-This function is used to configure time durations (such as timeouts) using
-the type
-xref:nng_duration.5.adoc[`nng_duration`].
-The duration is an integer number of milliseconds.
-
-`nng_stream_dialer_set_size()`::
-This function is used to configure a size, typically for buffer sizes,
-message maximum sizes, and similar options.
-
-`nng_stream_dialer_set_string()`::
-This function is used to pass configure a string.
-Strings passed this way must be legal UTF-8 or ASCII strings, terminated
-with a `NUL` (`\0`) byte.
-(Other constraints may apply as well, see the documentation for each option
-for details.)
-
-`nng_stream_dialer_set_uint64()`::
-This function is used to configure a 64-bit unsigned value/
-This is typically used for identifiers, network numbers,
-and similar options.
-
-`nng_stream_dialer_set_addr()`::
-This function is used to configure a
-xref:nng_sockaddr.5.adoc[socket address].
-The value is copied, and thus the caller may discard the supplied
-value immediately after this function returns.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The dialer is closed.
-`NNG_EINVAL`:: Either _data_ or _size_ are invalid.
-`NNG_ENOTSUP`:: The option is not supported.
-`NNG_EREADONLY`:: The option may not be modified.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)],
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
-xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
-xref:nng_tls_options.5.adoc[nng_tls_options(5)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_listener.5.adoc b/docs/man/nng_stream_listener.5.adoc
deleted file mode 100644
index b774a1b9..00000000
--- a/docs/man/nng_stream_listener.5.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-= nng_stream_listener(5)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener - byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stream_listener nng_stream_listener;
-----
-
-== DESCRIPTION
-
-(((IPC, listener)))
-An `nng_stream_listener` is a handle to a byte stream listener,
-which is responsible for accepting incoming connections and creating
-corresponding
-xref:nng_stream.5.adoc[`nng_stream`] from them.
-
-NOTE: The `nng_stream_listener` object is a low-level object for
-raw byte stream connections,
-and should not be confused with a high-level
-xref:nng_listener.5.adoc[`nng_listener`] object.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)],
-xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)],
-xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)],
-xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)],
-xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)],
-xref:nng_stream.5.adoc[nng_stream(5)],
-xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)]
diff --git a/docs/man/nng_stream_listener_accept.3str.adoc b/docs/man/nng_stream_listener_accept.3str.adoc
deleted file mode 100644
index f5ffbca5..00000000
--- a/docs/man/nng_stream_listener_accept.3str.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-= nng_stream_listener_accept(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_accept - accept incoming byte stream connection
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_listener_accept(nng_stream_listener *l, nng_aio *aio);
-----
-
-== DESCRIPTION
-
-The `nng_stream_listener_accept()` attempts to accept an incoming byte stream
-connection from a remote peer, using the listener _l_.
-The operation is completed asynchronously, using _aio_.
-
-This operation can only be done after the listener is already
-xref:nng_stream_listener_listen.3str.adoc[listening].
-
-If a connection is successfully established, the _aio_ will have the
-resulting
-xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output,
-which can be retrieved with
-xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECANCELED`:: The operation was aborted.
-`NNG_ECLOSED`:: The listener is closed.
-`NNG_ECONNRESET`:: The connection was reset by the peer.
-`NNG_ENOMEM`:: Insufficient free memory exists.
-`NNG_ESTATE`:: The listener is not not listening.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)],
-xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)],
-xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)],
-xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_stream.5.adoc[nng_stream(5)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_alloc.3str.adoc b/docs/man/nng_stream_listener_alloc.3str.adoc
deleted file mode 100644
index 966866ba..00000000
--- a/docs/man/nng_stream_listener_alloc.3str.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-= nng_stream_listener_alloc(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_alloc - allocate byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_listener_alloc(nng_stream_listener **lp, const char *addr);
-
-int nng_stream_listener_alloc_url(nng_stream_listener **lp, const nng_url *url);
-----
-
-== DESCRIPTION
-
-These functions allocates a listener for byte streams.
-Listeners create
-xref:nng_stream.5.adoc[`nng_stream`] objects by accepting incoming
-connections, via the
-xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]
-function.
-
-The first form, `nng_stream_listener_alloc()`, connects to the address
-specified by _addr_, which should be a string representing a URL.
-
-The second form, `nng_stream_listener_alloc_url()`, takes a pre-parsed
-or pre-constructed
-xref:nng_url.5.adoc[`nng_url`] object to determine the remote address.
-
-These functions may support different URL schemes, such as
-`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`.
-
-Both forms store the listener in the location referenced by _lp_.
-
-== RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists.
-`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation.
-`NNG_EADDRINVAL`:: The URL requested is invalid.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)]
-xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)]
-xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)]
-xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)]
-xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)]
-xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)]
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_close.3str.adoc b/docs/man/nng_stream_listener_close.3str.adoc
deleted file mode 100644
index a810509e..00000000
--- a/docs/man/nng_stream_listener_close.3str.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= nng_stream_listener_close(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_close - close byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_listener_close(nng_stream_listener *l);
-----
-
-== DESCRIPTION
-
-The `nng_stream_listener_close()` function closes the supplied connected byte
-stream listener _l_,
-but does not free the underlying resources associated with it.
-
-If any
-xref:nng_stream_listener_accept.3str.adoc[accept]
-operations using _d_ are
-in progress, they will be terminated with an `NNG_ECLOSED` error condition.
-
-Furthermore any future accesses to the listener _l_ will also result in
-`NNG_ECLOSED`.
-
-NOTE: This function does not release the memory for the listener, so the
-application should still free the memory using
-xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`]
-once it is certain that nothing else is using it.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)],
-xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)],
-xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_free.3str.adoc b/docs/man/nng_stream_listener_free.3str.adoc
deleted file mode 100644
index aecd8895..00000000
--- a/docs/man/nng_stream_listener_free.3str.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= nng_stream_listener_free(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-
-// 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_stream_listener_free - free byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_stream_listener_free(nng_stream_listener *)l;
-----
-
-== DESCRIPTION
-
-The `nng_stream_listener_free()` function closes the supplied
-byte stream listener _l_,
-and frees the underlying resources associated with it.
-
-If any
-xref:nng_stream_listener_accept.3str.adoc[accept] operations using __l are
-in progress, they will be terminated with an `NNG_ECLOSED` error condition.
-
-WARNING: It is important that the application ensure that no further accesses
-are made to _l_, as the memory backing it will be reclaimed for other uses.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)],
-xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)],
-xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_get.3str.adoc b/docs/man/nng_stream_listener_get.3str.adoc
deleted file mode 100644
index 3aeec857..00000000
--- a/docs/man/nng_stream_listener_get.3str.adoc
+++ /dev/null
@@ -1,110 +0,0 @@
-= nng_stream_listener_get(3str)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_get - get option from byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_listener_get_bool(nng_stream_listener *l, const char *opt, bool *valp);
-
-int nng_stream_listener_get_int(nng_stream_listener *l, const char *opt, int *valp);
-
-int nng_stream_listener_get_ms(nng_stream_listener *l, const char *opt, nng_duration *valp);
-
-int nng_stream_listener_get_size(nng_stream_listener *l, const char *opt, size_t *valp);
-
-int nng_stream_listener_get_addr(nng_stream_listener *l, const char *opt, nng_sockaddr *valp);
-
-int nng_stream_listener_get_string(nng_stream_listener *l, const char *opt, char **valp);
-
-int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint64_t *valp);
-----
-
-== DESCRIPTION
-
-
-The `nng_stream_listener_get` functions are used to retrieve option values
-for the
-xref:nng_stream_listener.5.adoc[byte stream listener] _l_.
-
-The actual options that may be retrieved in this way vary.
-A number of them are documented in
-xref:nng_options.5.adoc[nng_options(5)] and additional linked documents.
-
-=== Forms
-
-In all of these forms, the option _opt_ is retrieved from the connected
-byte stream listener _l_.
-The forms vary based on the type of the option they take.
-
-The details of the type, size, and semantics of the option will depend
-on the actual option, and will be documented with the option itself.
-
-`nng_stream_listener_get_bool()`::
-This function is for options which take a Boolean (`bool`).
-
-`nng_stream_listener_get_int()`::
-This function is for options which take an integer (`int`).
-
-`nng_stream_listener_get_ms()`::
-This function is used to retrieve time
-xref:nng_duration.5.adoc[durations]
-(such as timeouts), stored as a number of milliseconds.
-(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and
-the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.)
-
-`nng_stream_listener_get_size()`::
-This function is used to retrieve a size,
-typically for buffer sizes, message maximum sizes, and similar options.
-
-`nng_stream_listener_get_addr()`::
-This function is used to retrieve a
-xref:nng_sockaddr.5.adoc[socket address].
-
-`nng_stream_listener_get_string()`::
-This function is used to retrieve a `NULL`-terminated string.
-This string is created from the source using
-xref:nng_strdup.3.adoc[`nng_strdup()`]
-and consequently must be freed by the caller using
-xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed.
-
-`nng_stream_listener_get_uint64()`::
-This function is used to retrieve a 64-bit unsigned value.
-This is typically used for identifiers, network
-numbers, and similar options.
-
-== RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The listener is closed.
-`NNG_EINVAL`:: There was insufficient space to receive the object.
-	The amount of data actually needed is returned in _sizep_.
-`NNG_ENOTSUP`:: The option is not supported.
-`NNG_EWRITEONLY`:: The option may not read.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)],
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_listen.3str.adoc b/docs/man/nng_stream_listener_listen.3str.adoc
deleted file mode 100644
index e8473b52..00000000
--- a/docs/man/nng_stream_listener_listen.3str.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-= nng_stream_listener_listen(3str)
-//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_listen - bind listener to configured address
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_listener_listen(nng_stream_listener *l);
-----
-
-== DESCRIPTION
-
-The `nng_stream_listener_listen()` attempts to bind the listener _l_
-to the local address specified when the listener was created.
-
-This must generally be done before accepting incoming connections using
-xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`].
-
-For some transports this will also perform other actiosn.  For example,
-with TCP listeners it will configure the 
-underlying port into passive mode, ready to
-accept an incoming connection, and established a listen queue
-for receiving incoming connections.
-
-If binding the listener requires allocation of an address (for example
-when a TCP port number of zero is specified, indicating that an
-ephemeral port should be used), this operation will allocate that
-resource.
-This can permit retrieval of the selected address using
-xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`],
-typically with the
-xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_EADDRINUSE`:: The address is already in use.
-`NNG_EADDRINVAL`:: The address is invalid or unavailable.
-`NNG_ECLOSED`:: The listener has been closed.
-`NNG_ESTATE`:: The listener is already bound.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/man/nng_stream_listener_set.3str.adoc b/docs/man/nng_stream_listener_set.3str.adoc
deleted file mode 100644
index a623eef3..00000000
--- a/docs/man/nng_stream_listener_set.3str.adoc
+++ /dev/null
@@ -1,111 +0,0 @@
-= nng_stream_listener_set(3str)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-// Copyright 2019 Devolutions <info@devolutions.net>
-//
-// 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_stream_listener_set - set option on byte stream listener
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_stream_listener_set_bool(nng_stream_listener *l, const char *opt, bool val);
-
-int nng_stream_listener_set_int(nng_stream_listener *l, const char *opt, int val);
-
-int nng_stream_listener_set_ms(nng_stream_listener *l, const char *opt, nng_duration val);
-
-int nng_stream_listener_set_size(nng_stream_listener *l, const char *opt, size_t val);
-
-int nng_stream_listener_set_string(nng_stream_listener *l, const char *opt, const char *val);
-
-int nng_stream_listener_set_uint64(nng_stream_listener *l, const char *opt, uint64_t val);
-
-int nng_stream_listener_set_addr(nng_stream_listener *l, const char *opt, const nng_sockaddr *val);
-
-----
-
-== DESCRIPTION
-
-The `nng_stream_listener_set` functions are used to configure options for the
-xref:nng_stream.5.adoc[byte stream listener] _l_.
-The actual options that may be configured in this way vary, and are
-specified by _opt_.
-A number of them are documented in
-xref:nng_options.5.adoc[nng_options(5)].
-
-Additionally some transport-specific and protocol-specific options are
-documented with the transports and protocols themselves.
-
-=== Forms
-
-The details of the type, size, and semantics of the option will depend
-on the actual option, and will be documented with the option itself.
-
-`nng_stream_listener_set_bool()`::
-This function is for options which take a Boolean (`bool`).
-
-`nng_stream_listener_set_int()`::
-This function is for options which take an integer (`int`).
-
-`nng_stream_listener_set_ms()`::
-This function is used to configure time durations (such as timeouts) using
-the type
-xref:nng_duration.5.adoc[`nng_duration`].
-The duration is an integer number of milliseconds.
-
-`nng_stream_listener_set_size()`::
-This function is used to configure a size, typically for buffer sizes,
-message maximum sizes, and similar options.
-
-`nng_stream_listener_set_string()`::
-This function is used to pass configure a string.
-Strings passed this way must be legal UTF-8 or ASCII strings, terminated
-with a `NUL` (`\0`) byte.
-(Other constraints may apply as well, see the documentation for each option
-for details.)
-
-`nng_stream_listener_set_uint64()`::
-This function is used to configure a 64-bit unsigned value/
-This is typically used for identifiers, network numbers,
-and similar options.
-
-`nng_stream_listener_set_addr()`::
-This function is used to configure a
-xref:nng_sockaddr.5.adoc[socket address].
-The value is copied, and thus the caller may discard the supplied
-value immediately after this function returns.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The listener is closed.
-`NNG_EINVAL`:: Either _data_ or _size_ are invalid.
-`NNG_ENOTSUP`:: The option is not supported.
-`NNG_EREADONLY`:: The option may not be modified.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)],
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
-xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
-xref:nng_tls_options.5.adoc[nng_tls_options(5)],
-xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
diff --git a/docs/ref/api/stream.md b/docs/ref/api/stream.md
index b44593d2..ce312f84 100644
--- a/docs/ref/api/stream.md
+++ b/docs/ref/api/stream.md
@@ -104,4 +104,283 @@ are available, and which type they may be accessed using.
 In the case of `nng_stream_get_string`, the string is created as if by [`nng_strdup`], and must be freed by
 the caller using [`nng_strfree`] when no longer needed.
 
+## Stream Factories
+
+```c
+typedef struct nng_stream_dialer nng_stream_dialer;
+typedef struct nng_stream_listener nng_stream_listener;
+```
+
+{{hi:stream factory}}
+The {{i:`nng_stream_listener`}} object and {{i:`nng_stream_listener`}} objects can be thought of as factories that
+create [`nng_stream`] streams.
+
+The `nng_stream_listener` object a handle to a listener, which creates streams by accepting incoming connection requests.
+In a BSD socket implementation, this is the entity responsible for doing {{i:`bind`}}, {{i:`listen`}} and {{i:`accept`}}.
+Normally a listener may be used to accept multiple, possibly many, concurrent connections.
+
+The `nng_stream_dialer` object is a handle to a dialer, which creates streams by making outgoing
+connection requests. While there isn't a specific BSD socket analogue, this can be thought of as a factory for TCP sockets
+created by opening them with {{i:`socket`}} and then calling {{i:`connect`}} on them.
+
+## Creating a Stream Factory
+
+```c
+int nng_stream_dialer_alloc(nng_stream_dialer **dialerp, const char *url);
+int nng_stream_dialer_alloc_url(nng_stream_dialer **dialerp, const nng_url *url);
+int nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *url);
+int nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);
+```
+
+The {{i:`nng_stream_dialer_alloc`}} and {{i:`nng_stream_dialer_alloc_url`}} functions create a stream dialer, associated the
+{{i:URL}} specified by _url_ represented as a string, or as an [`nng_url`] object, respectively. The dialer is returned in the location
+_dialerp_ references.
+
+The {{i:`nng_stream_listener_alloc`}} and {{i:`nng_stream_listener_alloc_url`}} functions create a stream listener, associated the
+URL specified by _url_ represented as a string, or as an [`nng_url`] object, respectively. The listener is returned in the location
+_listenerp_ references.
+
+### Example 1: Creating a TCP Listener
+
+This shows creating a TCP listener that listens on `INADDR_ANY`, port 444.
+
+```c
+nng_listener listener;
+int rv = nng_stream_listener_alloc(&listener, "tcp://:444");
+```
+
+## Closing a Stream Factory
+
+```c
+void nng_stream_dialer_close(nng_stream_listener *dialer);
+void nng_stream_dialer_stop(nng_stream_listener *dialer);
+void nng_stream_dialer_free(nng_stream_listener *dialer);
+void nng_stream_listener_close(nng_stream_listener *listener);
+void nng_stream_listener_stop(nng_stream_listener *listener);
+void nng_stream_listener_free(nng_stream_listener *listener);
+```
+
+The {{i:`nng_stream_dialer_close`}} and {{i:`nng_stream_listener_close`}} functions close the stream _dialer_ or _listener_,
+preventing it from creating new connections.
+This will generally include closing any underlying file used for creating such connections.
+However, some requests may still be pending when this function returns, as it does not wait for the shutdown to complete.
+
+The {{i:`nng_stream_dialer_stop`}} and {{i:`nng_stream_listener_stop`}} functions performs the same action,
+but also wait until all outstanding requests are serviced, and the _dialer_ or _listener_ is completely stopped.
+Because they blocks, these functions must not be called in contexts where blocking is not allowed.
+
+The {{i:`nng_stream_dialer_free`}} and {{i:`nng_stream_listener_free`}} function performs the same action as
+`nng_stream_dialer_stop` or `nng_stream_listener_stop`, but also deallocates the _dialer_ or _listener_, and any associated resources.
+
+> [!TIP]
+> A best practice for shutting down an application safely is to stop everything _before_ deallocating. This ensures that no
+> callbacks are running that could reference an object after it is deallocated.
+
+## Making Outgoing Connections
+
+```c
+void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
+```
+
+The {{i:`nng_stream_dialer_dial`}} initiates an outgoing connection asynchronously, using the [`nng_aio`] _aio_.
+If it successfully establishes a connection, it creates an [`nng_stream`], which can be obtained as the first
+output result on _aio_ using the [`nng_aio_get_output`] function with index zero.
+
+> [!TIP]
+> An [`nng_stream_dialer`] can be used multiple times to make multiple concurrent connection requests, but
+> they all must reference the same URL.
+
+### Example 3: Connecting to Google
+
+This demonstrates making an outbound connection to "google.com" on TCP port 80.
+Error handling is elided for clarity.
+
+```c
+nng_aio *aio;
+nng_stream_dialer *dialer;
+nng_stream *stream;
+
+nng_stream_dialer_alloc(&dialer, "tcp://google.com:80");
+
+nng_aio_alloc(&aio, NULL, NULL);
+
+// make a single outbound connection
+nng_stream_dialer_dial(dialer, aio);
+nng_aio_wait(aio); // wait for the asynch operation to complete
+if (nng_aio_result(aio) != 0) {
+    // ... handle the error
+}
+stream = nng_aio_get_output(aio, 0);
+```
+
+## Accepting Incoming Connections
+
+```c
+int nng_stream_listener_listen(nng_stream_listener *listener);
+void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);
+```
+
+Accepting incoming connections is performed in two steps. The first step, {{i:`nng_stream_listener_listen`}} is to setup for
+listening. For a TCP implementation of this, for example, this would perform the `bind` and the `listen` steps. This will bind
+to the address represented by the URL that was specific when the listener was created with [`nng_stream_listener_alloc`].
+
+In the second step, {{i:`nng_stream_listener_accept`}} accepts an incoming connection on _listener_ asynchronously, using the [`nng_aio`] _aio_.
+If an incoming connection is accepted, it will be represented as an [`nng_stream`], which can be obtained from the _aio_ as the first
+output result using the [`nng_aio_get_output`] function with index zero.
+
+### Example 3: Accepting an Inbound Stream
+
+For clarity this example uses a synchronous approach using [`nng_aio_wait`], but a typical server application
+would most likely use a callback to accept the incoming stream, and start another instance of `nng_stream_listener_accept`.
+
+```c
+nng_aio *aio;
+nng_listener *listener;
+nng_stream *stream;
+
+nng_stream_listener_alloc(&listener, "tcp://:8181");
+nng_aio_alloc(&aio, NULL, NULL); // normally would use a callback
+
+// listen (binding to the URL in the process)
+if (nng_stream_listener_listen(listener)) {
+    // ... handle the error
+}
+
+// now accept a single incoming connection as a stream object
+nng_stream_listener_accept(l, aio);
+nng_aio_wait(aio); // wait for the asynch operation to complete
+if (nng_aio_result(aio) != 0) {
+    // ... handle the error
+}
+stream = nng_aio_get_output(aio, 0);
+```
+
+## Stream Factory Options
+
+```c
+int nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, bool *valp);
+int nng_stream_dialer_get_int(nng_stream_dialer *dialer, const char *opt, int *valp);
+int nng_stream_dialer_get_ms(nng_stream_dialer *dialer, const char *opt, nng_duration *valp);
+int nng_stream_dialer_get_size(nng_stream_dialer *dialer, const char *opt, size_t *valp);
+int nng_stream_dialer_get_addr(nng_stream_dialer *dialer, const char *opt, nng_sockaddr *valp);
+int nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, char **valp);
+int nng_stream_dialer_get_uint64(nng_stream_dialer *dialer, const char *opt, uint64_t *valp);
+
+int nng_stream_listener_get_bool(nng_stream_listener *listener, const char *opt, bool *valp);
+int nng_stream_listener_get_int(nng_stream_listener *listener, const char *opt, int *valp);
+int nng_stream_listener_get_ms(nng_stream_listener *listener, const char *opt, nng_duration *valp);
+int nng_stream_listener_get_size(nng_stream_listener *listener, const char *opt, size_t *valp);
+int nng_stream_listener_get_addr(nng_stream_listener *listener, const char *opt, nng_sockaddr *valp);
+int nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, char **valp);
+int nng_stream_listener_get_uint64(nng_stream_listener *listener, const char *opt, uint64_t *valp);
+
+int nng_stream_dialer_set_bool(nng_stream_dialer *dialer, const char *opt, bool val);
+int nng_stream_dialer_set_int(nng_stream_dialer *dialer, const char *opt, int val);
+int nng_stream_dialer_set_ms(nng_stream_dialer *dialer, const char *opt, nng_duration val);
+int nng_stream_dialer_set_size(nng_stream_dialer *dialer, const char *opt, size_t val);
+int nng_stream_dialer_set_string(nng_stream_dialer *dialer, const char *opt, const char *val);
+int nng_stream_dialer_set_uint64(nng_stream_dialer *dialer, const char *opt, uint64_t val);
+int nng_stream_dialer_set_addr(nng_stream_dialer *dialer, const char *opt, const nng_sockaddr *val);
+
+int nng_stream_listener_set_bool(nng_stream_listener *listener, const char *opt, bool val);
+int nng_stream_listener_set_int(nng_stream_listener *listener, const char *opt, int val);
+int nng_stream_listener_set_ms(nng_stream_listener *listener, const char *opt, nng_duration val);
+int nng_stream_listener_set_size(nng_stream_listener *listener, const char *opt, size_t val);
+int nng_stream_listener_set_string(nng_stream_listener *listener, const char *opt, const char *val);
+int nng_stream_listener_set_uint64(nng_stream_listener *listener, const char *opt, uint64_t val);
+int nng_stream_listener_set_addr(nng_stream_listener *listener, const char *opt, const nng_sockaddr *val);
+```
+
+{{hi:`nng_stream_dialer_get_bool`}}
+{{hi:`nng_stream_dialer_get_int`}}
+{{hi:`nng_stream_dialer_get_ms`}}
+{{hi:`nng_stream_dialer_get_size`}}
+{{hi:`nng_stream_dialer_get_addr`}}
+{{hi:`nng_stream_dialer_get_string`}}
+{{hi:`nng_stream_dialer_get_uint64`}}
+{{hi:`nng_stream_dialer_set_bool`}}
+{{hi:`nng_stream_dialer_set_int`}}
+{{hi:`nng_stream_dialer_set_ms`}}
+{{hi:`nng_stream_dialer_set_size`}}
+{{hi:`nng_stream_dialer_set_addr`}}
+{{hi:`nng_stream_dialer_set_string`}}
+{{hi:`nng_stream_dialer_set_uint64`}}
+{{hi:`nng_stream_listener_get_bool`}}
+{{hi:`nng_stream_listener_get_int`}}
+{{hi:`nng_stream_listener_get_ms`}}
+{{hi:`nng_stream_listener_get_size`}}
+{{hi:`nng_stream_listener_get_addr`}}
+{{hi:`nng_stream_listener_get_string`}}
+{{hi:`nng_stream_listener_get_uint64`}}
+{{hi:`nng_stream_listener_set_bool`}}
+{{hi:`nng_stream_listener_set_int`}}
+{{hi:`nng_stream_listener_set_ms`}}
+{{hi:`nng_stream_listener_set_size`}}
+{{hi:`nng_stream_listener_set_addr`}}
+{{hi:`nng_stream_listener_set_string`}}
+{{hi:`nng_stream_listener_set_uint64`}}
+These functions are used to retrieve or change the value of an option named _opt_ from the stream _dialer_ or _listener_.
+The `nng_stream_dialer_get_` and `nng_stream_listener_get_` function families retrieve the value, and store it in the location _valp_ references.
+The `nng_stream_dialer_set_` and `nng_stream_listener_set_` function families change the value for the _dialer_ or _listener_, taking it from _val_.
+
+These functions access an option as a specific type. The transport layer will have details about which options
+are available, and which type they may be accessed using.
+
+In the case of `nng_stream_dialer_get_string` and `nng_stream_listener_get_string`, the string is created as if by [`nng_strdup`], and must be freed by
+the caller using [`nng_strfree`] when no longer needed.
+
+In the case of `nng_stream_dialer_set_string` and `nng_stream_listener_set_string`, the string contents are copied if necessary, so that the caller
+need not retain the value referenced once the function returns.
+
+In the case of `nng_stream_dialer_set_addr` and `nng_stream_listener_set_addr`, the contents of _addr_ are copied if necessary, so that the caller
+need not retain the value referenced once the function returns.
+
+### Example 4: Socket Activation<a name="socket-activation"></a>
+
+Some [`nng_stream_listener`] objects, depending on the underlying transport and platform, can support a technique known as "{{i:socket activation}}",
+where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
+In this case, the application supplies the file descriptor or `SOCKET` object using the {{i:`NNG_OPT_LISTEN_FD`}} option,
+instead of calling [`nng_stream_listener_listen`].
+
+> [!TIP]
+> Scalability Protocols transports based upon stream implementations that support socket activation can also benefit from this approach.
+
+```c
+nng_stream_listener *listener;
+int fd;
+
+// This is a systemd API, not part of NNG.
+// See systemd documentation for an explanation.
+// fd at this point has already had bind() and listen() called.
+fd = SD_LISTEN_FDS_START + 0;
+
+nng_stream_listener_alloc(&listener, "tcp://");
+nng_stream_listener_set_int(listener, NNG_OPT_LISTEN_FD, fd);
+
+// can now start doing nng_stream_listener_accept...
+```
+
+## TLS Configuration
+
+```c
+int nng_stream_dialer_get_tls(nng_stream_listener *dialer, nng_tls_config **tlsp);
+int nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *tls);
+int nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
+int nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
+```
+
+Both [`nng_stream_dialer`] and [`nng_stream_listener`] objects may support configuration of {{i:TLS}} parameters.
+The {{i:`nng_stream_dialer_set_tls`}} and {{i:`nng_stream_listener_set_tls`}} functions support setting the
+configuration of a [`nng_tls_config`] object supplied by _tls_ on _dialer_ or _listener_.
+This must be performed before the _listener_ starts listening with [`nng_stream_listener_listen`], or the dialer starts an outgoing connection
+as a result of [`nng_stream_dialer_dial`].
+
+The configuration object that was previously established (which may be a default if one was not explicitly
+configured) can be obtained with the {{i:`nng_stream_dialer_get_tls`}} and {{i:`nng_stream_listener_get_tls`}}.
+They will return a pointer to the [`nng_tls_config`] object in question at the location referenced by _tlsp_.
+
+> [!NOTE]
+> TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to
+> both configuring a different TLS configuration object, as well as mutating the existing [`nng_tls_config`] object.
+
 {{#include ../xref.md}}
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index e31f4847..88958feb 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -93,6 +93,8 @@
 [`nng_aio_count`]: /api/aio.md#result-of-operation
 [`nng_aio_set_timeout`]: /api/aio.md#set-timeout
 [`nng_aio_set_iov`]: /api/aio.md#scatter-gather-vectors
+[`nng_aio_get_output`]: /api/aio.md#inputs-and-outputs
+[`nng_aio_set_input`]: /api/aio.md#inputs-and-outputs
 [`nng_iov`]: /api/aio.md#scatter-gather-vectors
 [`nng_socket_id`]: /api/sock.md#socket-identity
 [`nng_socket_raw`]: /api/sock.md#socket-identity
@@ -117,6 +119,53 @@
 [`nng_stream_get_addr`]: /api/stream.md#getting-stream-options
 [`nng_stream_get_string`]: /api/stream.md#getting-stream-options
 [`nng_stream_get_uint64`]: /api/stream.md#getting-stream-options
+[`nng_stream_dialer`]: /api/stream.md#stream-factories
+[`nng_stream_listener`]: /api/stream.md#stream-factories
+[`nng_stream_dialer_alloc`]: /api/stream.md#creating-a-stream-factory
+[`nng_stream_dialer_alloc_url`]: /api/stream.md#creating-a-stream-factory
+[`nng_stream_listener_alloc`]: /api/stream.md#creating-a-stream-factory
+[`nng_stream_listener_alloc_url`]: /api/stream.md#creating-a-stream-factory
+[`nng_stream_dialer_close`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_dialer_stop`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_dialer_free`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_listener_close`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_listener_stop`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_listener_free`]: /api/stream.md#closing-a-stream-factory
+[`nng_stream_dialer_dial`]: /api/stream.md#making-outgoing-connections
+[`nng_stream_listener_listen`]: /api/stream.md#accepting-incoming-connections
+[`nng_stream_listener_accept`]: /api/stream.md#accepting-incoming-connections
+[`nng_stream_listener_set_tls`]: /api/stream.md#tls-configuration
+[`nng_stream_listener_get_tls`]: /api/stream.md#tls-configuration
+[`nng_stream_dialer_set_tls`]: /api/stream.md#tls-configuration
+[`nng_stream_dialer_get_tls`]: /api/stream.md#tls-configuration
+[`nng_stream_dialer_get_bool`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_int`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_ms`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_size`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_addr`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_string`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_get_uint64`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_bool`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_int`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_ms`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_size`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_addr`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_string`]: /api/stream.md#stream-factory-options
+[`nng_stream_dialer_set_uint64`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_bool`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_int`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_ms`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_size`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_addr`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_string`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_get_uint64`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_bool`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_int`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_ms`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_size`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_addr`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_string`]: /api/stream.md#stream-factory-options
+[`nng_stream_listener_set_uint64`]: /api/stream.md#stream-factory-options
 [`nng_init`]: /api/init.md#initialization
 [`nng_fini`]: /api/init.md#finalization
 [`nng_sub0_ctx_subscribe`]: /TODO.md
@@ -235,6 +284,7 @@
 [`NNG_UNIT_EVENTS`]: /api/stats.md#statistic-units
 [`NNG_FLAG_ALLOC`]: /TODO.md
 [`NNG_FLAG_NONBLOCK`]: /TODO.md
+[`NNG_OPT_LISTEN_FD`]: /api/streams.md#socket-activation
 [`NNG_OPT_MAXTTL`]: /TODO.md
 [`NNG_OPT_RECONNMAXT`]: /TODO.md
 [`NNG_OPT_RECONNMINT`]: /TODO.md