Add dialer documentation.

1 files changed, 109 insertions, 0 deletions

diff --git a/docs/nng_dialer_getopt.adoc b/docs/nng_dialer_getopt.adoc
new file mode 100644
index 00000000..8275d46b
--- /dev/null
+++ b/docs/nng_dialer_getopt.adoc
@@ -0,0 +1,109 @@
+= nng_dialer_getopt(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_getopt - get dialer option
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp);
+int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp);
+int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp);
+int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr);
+int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t *zp);
+int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
+-----------
+
+== DESCRIPTION
+
+The `nng_dialer_getopt()` functions are used to retrieve option values for
+the dialer _d_. The actual options that may be retrieved in this way
+vary, and are documented in the <<nng_getopt#,nng_getopt(3)>> manual.
+Additionally some transport-specific options are documented with the
+transports themselves.
+
+In all of these forms, the option _opt_ is retrieved from 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_getopt()`, can be used to
+retrieve the value of any option.  It is untyped.  The caller must store
+a pointer to a buffer to receive the value in _val_, and the size of the
+buffer shall be stored at the location referenced by _valszp_.
+
+When the function returns, the actual size of the data copied (or that
+would have been copied if sufficient space were present) is stored at
+the location referened by _valszp_.  If the caller's buffer is not large
+enough to hold the entire object, then the copy is truncated.  Therefore
+the caller should validate that the returned size in _valszp_ does not
+exceed the original buffer size to check for truncation.
+
+It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero.
+This can be used to determine the size of the buffer needed to receive
+the object.
+
+Generally, it will be easier to use one of the typed forms instead.  Note
+however that no validation that the option is actually of the associated
+type is performed, so the caller must take care to use the *correct* typed
+form.
+
+The second form, `nng_dialer_getopt_int()`,
+is for options which take an integer (or boolean).  The value will
+be stored at _ivalp_.  For booleans the value will be eiher 0 (false) or 1 (true).
+
+The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations
+(such as timeouts), stored in _durp_ as a number of milliseconds.
+(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and
+the special value `NNG_DUR_DEFAULT` means a context-specific default.)
+
+The fourth form, `nng_dialer_getopt_ptr()`, is used to retrieve a
+pointer _ptr_ to structured data.  The data referenced by _ptr_ is
+generally managed using other functions.
+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_getopt_size()`, is used to retrieve a size
+into the pointer _zp_, typically for buffer sizes, message maximum sizes, and
+similar options.
+
+The sixth form, `nng_diale_getopt_uint64()`, is used to retrieve a
+64-bit unsigned value into the value referenced by _u64p_.
+This is typically used for options
+related to identifiers, network numbers, and similar.
+
+== 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_ENOTSUP`:: The option _opt_ is not supported.
+`NNG_EWRITEONLY`:: The option _opt_ is write-only.
+
+== SEE ALSO
+
+<<nng_listen#,nng_listen(3)>>,
+<<nng_dialer_create#,nng_dialer_create(3)>>
+<<nng_dialer_setopt#,nng_dialer_setopt(3)>>
+<<nng_getopt#,nng_getopt(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file