1 files changed, 104 insertions, 0 deletions
diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc
new file mode 100644
index 00000000..80780884
--- /dev/null
+++ b/docs/man/nng_device.3.adoc
@@ -0,0 +1,104 @@
+= nng_device(3)
+//
+// Copyright 2018 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_sendmsg - send message
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_device(nng_socket s1, nng_socket s2);
+----
+
+== DESCRIPTION
+
+The `nng_device()` function forwards messages received from one
+<<nng_socket.5#,socket>> _s1_ to another socket _s2_, and vice versa.
+
+This function is used to create forwarders, which can be used to create
+complex network topologies to provide for improved ((horizontal scalability)),
+reliability, and isolation.
+
+The `nng_device()` function does not return until one of the sockets
+is closed.
+
+=== Reflectors
+
+One of the sockets may be passed the special value `-1` (cast to an,
+<<nng_socket.5#,`nng_socket`>> of course).
+If this is the case, then the other socket must be valid, and must be
+a protocol that is bidirectional and can peer with itself (such as
+<<nng_pair.7#,_pair_>> or
+<<nng_bus.7#,_bus_>>.)
+In this case the device acts as a ((reflector)) or loop-back device,
+where messages received from the valid socket are merely returned
+back to the sender.
+
+=== Forwarders
+
+When both sockets are valid, then the result is a ((forwarder)) or proxy.
+In this case sockets _s1_ and _s2_ must be "`compatible`" with each other,
+which is to say that they should represent the opposite halves of a two
+protocol pattern, or both be the same protocol for a single protocol
+pattern.
+For example, if _s1_ is a <<nng_pub.7#,_pub_>> socket, then _s2_ must 
+be a <<nng_sub.7#,_sub_>> socket.
+Or, if _s1_ is a <<nng_bus.7#,_bus_>> socket, then _s2_ must also
+be a _bus_ socket.
+
+=== Operation
+
+This `nng_device()` function puts each socket into raw mode
+(see <<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>), and then moves messages
+between them.
+When a protocol has a ((backtrace)) style header, routing information is
+added as the message crosses the forwarder, allowing replies to be
+returned to requestors, and responses to be routed back to surveyors.
+
+Additionally, some protocols have a maximum ((time-to-live)) to protect
+against forwarding loops and especially amplification loops.
+In these cases, the default limit (usually 8), ensures that messages will
+self-terminate when they have passed through too many forwarders,
+protecting the network from unlimited message amplification that can arise
+through misconfiguration.
+This is controlled via the <<nng_options.5#NNG_OPT_MAXTTL,`NNG_OPT_MAXTTL`>>
+option.
+
+IMPORTANT: Not all protocols have support for guarding against forwarding loops,
+and even for those that do, forwarding loops can be extremely determintal
+to network performance.
+
+NOTE: Devices (forwarders and reflectors) act in best effort delivery mode only.
+If a message is received from one socket that cannot be accepted by the
+other (due to backpressure or other issues), then the message is discarded.
+
+TIP: Use the request/reply pattern, which includes automatic retries by
+the requestor, if reliable delivery is needed.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ECLOSED`:: At least one of the sockets is not open.
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_EINVAL`:: The sockets are not compatible, or are both invalid.
+
+== SEE ALSO
+
+<<nng_options.5#,nng_options(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng.7#,nng(7)>>