From 98f23e10cc1d65da6a7f6c7e4f5665d7afc27a86 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 15 Mar 2018 08:40:17 -0700
Subject: fixes #286 nng_pair0_open (and all others) need man page fixes #279
 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)
---
 docs/man/nng_dialer_start.3.adoc | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 docs/man/nng_dialer_start.3.adoc

(limited to 'docs/man/nng_dialer_start.3.adoc')

diff --git a/docs/man/nng_dialer_start.3.adoc b/docs/man/nng_dialer_start.3.adoc
new file mode 100644
index 00000000..45dd0d6f
--- /dev/null
+++ b/docs/man/nng_dialer_start.3.adoc
@@ -0,0 +1,75 @@
+= nng_dialer_start(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_dialer_start - start dialer
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_dialer_start(nng_dialer d, int flags);
+----
+
+== DESCRIPTION
+
+The `nng_dialer_start()` function starts the dialer _d_.
+
+This causes the dialer to start connecting to the address with which it was
+created.
+
+When a connection is established, it results in a pipe being created,
+which will be attached to the dialer's socket.
+
+Normally, the first attempt to connect to the dialer's address 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.
+
+Once a dialer has started, it is generally not possible to change
+its configuration.
+
+== 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_ESTATE`:: The dialer _d_ is already started.
+`NNG_EUNREACHABLE`:: The remote address is not reachable.
+
+== SEE ALSO
+
+<<nng_dial.3#,nng_dial(3)>>,
+<<nng_dialer_create.3#,nng_dialer_create(3)>>
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_dialer.5#,nng_dialer(5)>>,
+<<nng.7#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

