Add dialer documentation.

1 files changed, 91 insertions, 0 deletions

diff --git a/docs/nng_dial.adoc b/docs/nng_dial.adoc
new file mode 100644
index 00000000..f3cff465
--- /dev/null
+++ b/docs/nng_dial.adoc
@@ -0,0 +1,91 @@
+= nng_dial(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_dial - create and start dialer
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags);
+-----------
+
+== DESCRIPTION
+
+The `nng_dialer()` function creates a newly initialized
+dialer, associated with socket _s_, and configured to listen at the
+address specified by _url_.  If the value of _dp_ is not `NULL`, then
+the newly created dialer is stored at the address indicated by _dp_.
+
+Dialers initiate a remote connection to a listener. Upon a successful
+connection being established, they create a pipe, add it to the socket,
+and then wait for that pipe to be closed.  When the pipe is closed,
+they will re-initiate the connection.  Dialer's will also periodically
+retry a connection automatically if an attempt to connect asynchronously
+fails.
+
+TIP: While it is convenient to think of dialers as "clients", the relationship
+between the listener or dialer is orthogonal to any server or client status
+that might be associated with a given protocol.  For example, a <<nng_req#,REQ>>
+socket might have associated dialers, but might also have associated listeners.
+It may even have some of each at the same time!
+
+Normally, the first attempt to connect to the address indicated by _url_ is done
+synchronously, including any necessary name resolution.  As a result,
+a failure, such as if the connection is refused, will be returned
+immediately, and no further action will be taken. 
+
+However, if the special value `NNG_FLAG_NONBLOCK` is
+supplied in _flags_, then the connection attempt is made asynchronously.
+
+Furthermore, if the connection was closed for a synchronously dialed
+connection, the dialer will still attempt to redial asynchronously.
+
+TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient,
+it also generally makes diagnosing failures somewhat more difficult.
+
+Because the dialer is started immediately, it is generally not possible
+to apply extra configuration; if that is needed applications should consider
+using <<nng_dialer_create#,nng_dialer_create(3)>> and 
+<<nng_dialer_start#,nng_dialer_start(3)>> instead.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EADDRINVAL`:: An invalid _url_ was specified.
+`NNG_ECLOSED`:: The socket _s_ is not open.
+`NNG_ECONNREFUSED`:: The remote peer refused the connection.
+`NNG_ECONNRESET`:: The remote peer reset the connection.
+`NNG_EINVAL`:: An invalid set of _flags_ was specified.
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_EPEERAUTH`:: Authentication or authorization failure.
+`NNG_EPROTO`:: A protocol error occurred.
+`NNG_EUNREACHABLE`:: The remote address is not reachable.
+
+== SEE ALSO
+
+<<nng_dialer_close#,nng_dialer_close(3)>>,
+<<nng_dialer_create#,nng_dialer_create(3)>>
+<<nng_dialer_start#,nng_dialer_start(3)>>,
+<<nng_listen#,nng_listen(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}