1 files changed, 136 insertions, 0 deletions
diff --git a/docs/man/nng_req.adoc b/docs/man/nng_req.adoc
new file mode 100644
index 00000000..550c90c4
--- /dev/null
+++ b/docs/man/nng_req.adoc
@@ -0,0 +1,136 @@
+= nng_req(7)
+//
+// 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_req - request protocol
+
+== SYNOPSIS
+
+[source,c]
+----------
+#include <nng/protocol/reqrep0/req.h>
+
+int nng_req0_open(nng_socket *s);
+----------
+
+== DESCRIPTION
+
+The _nng_req_ protocol is one half of a request/reply pattern.
+In this pattern, a requester sends a message to one replier, who
+is expected to reply.  The request is resent if no reply arrives,
+until a reply is received or the request times out.
+
+TIP: This protocol is useful in setting up RPC-like services.  It
+is also "reliable", in that a the requester will keep retrying until
+a reply is received.
+
+NOTE: Because requests are resent, it is important that they be idempotent
+to ensure predictable and repeatable behavior even in the face of duplicated
+requests, which can occur (for example if a reply message is lost for
+some reason.)
+
+The requester generally only has one outstanding request at a time unless
+in "raw" mode (via `NNG_OPT_RAW`), and it will generally attempt to spread
+work requests to different peer repliers.
+
+TIP: This property, when combined with a <<nng_device#,device>> can
+help provide a degree of load-balancing.
+
+The _nng_req_ protocol is the requester side, and the
+<<nng_rep#,nng_rep(7)>> protocol is the replier side.
+
+=== Socket Operations
+
+The `nng_req0_open()` call creates a requester socket.  This socket
+may be used to send messages (requests), and then to receive replies.  Generally
+a reply can only be received after sending a request.  (Attempts to receive
+a message will result in `NNG_ESTATE` if there is no outstanding request.)
+
+Requests may be canceled by sending a different request.  This will
+cause the requester to discard any reply from the earlier request,
+but it will not stop a replier
+from processing a request it has already received or terminate a request
+that has already been placed on the wire.
+
+Attempts to receive on a socket with no outstanding requests will result
+in `NNG_ESTATE`. 
+
+Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions.
+
+=== Protocol Versions
+
+Only version 0 of this protocol is supported.  (At the time of writing,
+no other versions of this protocol have been defined.)
+
+=== Protocol Options
+
+The following protocol-specific options are available.
+
+`NNG_OPT_REQ_RESENDTIME`::
+
+   This read/write option is a duration (32-bit unsigned integer) representing
+   a relative number of milliseconds. 
+   When a new request is started, a timer of this duration is also started.
+   If no reply is received before this timer expires, then the request will
+   be resent.  (Requests are also automatically resent if the peer to whom
+   the original request was sent disconnects, or if a peer becomes available
+   while the requester is waiting for an available peer.)
+
+`NNG_OPT_MAXTTL`::
+
+   Maximum time-to-live.  This option is an integer value
+   between 0 and 255,
+   inclusive, and is the maximum number of "hops" that a message may
+   pass through until it is discarded.  The default value is 8.  A value
+   of 0 may be used to disable the loop protection, allowing an infinite
+   number of hops.
+
+=== Protocol Headers
+
+This protocol uses a _backtrace_ in the header.  This
+form uses a "stack" of 32-bit big-endian identifiers.  There *must* be
+at least one identifier, the __request ID__, which will be the last
+element in the array, and *must* have the most significant bit set.
+
+There may be additional __peer ID__s preceeding the request ID.  These
+will be distinguishable from the request ID by having their most
+significant bit clear.
+
+When a request message is received by a forwarding node (see
+<<nng_device#,nng_device(3)>>), the forwarding node prepends a
+32-bit peer ID (which *must* have the most significant bit clear),
+which is the forwarder's way of identifying the directly connected
+peer from which it received the message.  (This peer ID, except for the
+most significant bit, has meaning only to the forwarding node itself.)
+
+It may help to think of prepending a peer ID as "pushing" a peer ID onto the
+front of the stack of headers for the message.  (It will use the peer ID
+it popped from the front to determine the next intermediate destination
+for the reply.)
+
+When a reply message is created, it is created using the same headers
+that the request contained.
+
+A forwarding node can "pop" the peer ID it originally pushed on the
+message, stripping it from the front of the message as it does so.
+
+When the reply finally arrives back at the initiating requestor, it
+should have only a single element in the message, which will be the
+request ID it originally used for the request.
+
+// TODO: Insert reference to RFC.
+
+== SEE ALSO
+
+<<nng_device(3)#,nng_device(3)>>,
+<<nng#,nng(7)>>,
+<<nng_rep#,nng_rep(7)>>