1 files changed, 138 insertions, 0 deletions
diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc
new file mode 100644
index 00000000..9d93eade
--- /dev/null
+++ b/docs/man/nng_req.7.adoc
@@ -0,0 +1,138 @@
+= 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
+
+(((protocol, _req_)))
+The ((_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.)
+
+(((load-balancing)))
+The requester generally only has one outstanding request at a time unless
+in "raw" mode (via
+<<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>),
+and it will generally attempt to spread work requests to different peer repliers.
+
+TIP: This property, when combined with <<nng_device.3#,`nng_device()`>>
+can help provide a degree of load-balancing.
+
+The _req_ protocol is the requester side, and the
+<<nng_rep.7#,_rep_>> protocol is the replier side.
+
+=== Socket Operations
+
+The <<nng_req_open.3#,`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_options.5#NNG_OPT_RAW,`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 option is 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.)
+
+=== Protocol Headers
+
+(((backtrace)))
+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.3#,`nng_device()`>>), 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_req_open.3#,nng_req_open(3)>>,
+<<nng.7#,nng(7)>>,
+<<nng_rep.7#,nng_rep(7)>>