Add dialer documentation.

1 files changed, 108 insertions, 0 deletions

diff --git a/docs/nng_dialer_setopt.adoc b/docs/nng_dialer_setopt.adoc
new file mode 100644
index 00000000..2c54f0e3
--- /dev/null
+++ b/docs/nng_dialer_setopt.adoc
@@ -0,0 +1,108 @@
+= nng_dialer_setopt(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_dialer_setopt - set dialer option
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val,
+    size_t valsz);
+int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival);
+int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur);
+int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr);
+int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z);
+int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str);
+int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64);
+-----------
+
+== DESCRIPTION
+
+The `nng_dialer_setopt()` functions are used to configure options for
+the dialer _d_. The actual options that may be configured in this way
+vary, and are documented in the <<nng_setopt#,nng_setopt(3)>> manual.
+Additionally some transport-specific options are documented with the
+transports themselves.
+
+In all of these forms, the option _opt_ is configured on the dialer _d_.
+
+The details of the type, size, and semantics of the option will depend
+on the actual option, and will be documented with the option itself.
+
+The first form of this function, `nng_dialer_setopt()`, can be used to
+configure any arbitrary data.
+The _val_ pointer addresses the data to copy, and _valsz_ is the
+size of the objected located at _val_.
+
+Generally, it will be easier to use one of the typed forms instead.
+
+The second form, `nng_dialer_setopt_int()`,
+is for options which take an integer (or boolean).  The _ival_
+is passed to the option.  For booleans pass either 0 (false) or 1 (true).
+
+The third form, `nng_dialer_setopt_ms()`, is used to configure time durations
+(such as timeouts).
+The duration _dur_ is an integer number of milliseconds.  (The special value
+`NNG_DUR_INFINITE` means an infinite amount of time.)
+
+The fourth form, `nng_dialer_setopt_ptr()`, is used to pass a
+pointer _ptr_ to structured data.  The data referenced by _ptr_ is
+generally managed by other functions.
+For example, TLS configuration objects
+(<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>) can be passed this way.
+Note that this form is somewhat special in that the object is generally
+not copied, but instead the *pointer* to the object is copied.
+
+The fifth form, `nng_dialer_setopt_size()`, is used to pass a size
+specified by _z_, typically for buffer sizes, message maximum sizes, and
+similar options.
+
+The sixth form, `nng_dialer_setopt_string()`, is used to pass a string
+_str_.  Strings passed this way must be legal UTF-8 or ASCII strings, terminated
+with a `NUL` (`\0`) byte.  (Other constraints may apply as well, see the
+documentation for _opt_ for details.)
+
+The seventh form, `nng_dialer_setopt_uint64()`, is used to configure
+the 64-bit unsigned value in _u64_.  This is typically used for options
+related to identifiers, network numbers, and similar.
+
+NOTE: Once a dialer has started, it is generally not possible to change
+it's configuration.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer.
+`NNG_EINVAL`:: The value being passed is invalid.
+`NNG_ENOTSUP`:: The option _opt_ is not supported.
+`NNG_EREADONLY`:: The option _opt_ is read-only.
+`NNG_ESTATE`:: The dialer _d_ is already started.
+
+== SEE ALSO
+
+<<nng_dial#,nng_dial(3)>>,
+<<nng_dialer_create#,nng_dialer_create(3)>>
+<<nng_dialer_getopt#,nng_dialer_getopt(3)>>
+<<nng_setopt#,nng_setopt(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file