Add nng_listen* man pages.

8 files changed, 512 insertions, 9 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index 2ce2732b..60e9fad4 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -40,13 +40,28 @@ The following common functions exist in _libnng_.
 The following functions operate on sockets.
 
 |===
-|<<nng_close#,nng_close(3)>>|close a socket
-|<<nng_dial#,nng_dial(3)>>|create and start a dialer
-|<<nng_getopt#,nng_getopt(3)>>|get a socket option
-|<<nng_listen#,nng_listen(3)>>|create and start a listener
+|<<nng_close#,nng_close(3)>>|close socket
+|<<nng_dial#,nng_dial(3)>>|create and start dialer
+|<<nng_getopt#,nng_getopt(3)>>|get socket option
+|<<nng_listen#,nng_listen(3)>>|create and start listener
 |<<nng_recv#,nng_recv(3)>>|receive data
 |<<nng_send#,nng_send(3)>>|send data
-|<<nng_setopt#,nng_setopt(3)>>|set a socket option
+|<<nng_setopt#,nng_setopt(3)>>|set socket option
+|===
+
+=== Connection Management
+
+The following functions are used with either listeners, or dialers.
+Listeners accept incoming connection requets, and dialers make them.
+
+|===
+|<<nng_dial#,nng_dial(3)>>|create and start dialer
+|<<nng_listen#,nng_listen(3)>>|create and start listener
+|<<nng_listener_close#,nng_listener_close(3)>>|close listener
+|<<nng_listener_create#,nng_listener_create(3)>>|create listener
+|<<nng_listener_getopt#,nng_listener_getopt(3)>>|get listener option
+|<<nng_listener_setopt#,nng_listener_setopt(3)>>|set listener option
+|<<nng_listener_start#,nng_listener_start(3)>>|start listener
 |===
 
 === Message Handling Functions
diff --git a/docs/nng_close.adoc b/docs/nng_close.adoc
index 9a582f83..58f31f83 100644
--- a/docs/nng_close.adoc
+++ b/docs/nng_close.adoc
@@ -11,7 +11,7 @@
 
 == NAME
 
-nng_close - close a socket
+nng_close - close socket
 
 == SYNOPSIS
 
@@ -19,12 +19,12 @@ nng_close - close a socket
 -----------
 #include <nng/nng.h>
 
-int nng_close(int s);
+int nng_close(nng_socket s);
 -----------
 
 == DESCRIPTION
 
-The `nng_close()` function closes the supplied socket, 's'.  Messages
+The `nng_close()` function closes the supplied socket, _s_.  Messages
 that have been submitted for sending may be flushed or delivered,
 depending upon the transport and the setting of the `NNG_OPT_LINGER`
 option.
@@ -39,7 +39,7 @@ This function returns 0 on success, and non-zero otherwise.
 
 == ERRORS
 
-`NNG_EBADF`:: The socket is already closed or was never opened.
+`NNG_EBADF`:: The socket _s_ is already closed or was never opened.
 
 == SEE ALSO
 
diff --git a/docs/nng_listen.adoc b/docs/nng_listen.adoc
new file mode 100644
index 00000000..56552f01
--- /dev/null
+++ b/docs/nng_listen.adoc
@@ -0,0 +1,84 @@
+= nng_listen(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_listen - create and start listener
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listen(nng_socket s, const char *url, nng_listener *lp, int flags);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener()` function creates a newly initialized
+listener, associated with socket _s_, and configured to listen at the
+address specified by _url_.  If the value of _lp_ is not `NULL`, then
+the newly created listener is stored at the address indicated by _lp_.
+
+Listeners are used to accept connections initiated by remote dialers.  An
+incoming connection generally results in a pipe being created and attached
+to the socket _s_.  Unlike dialers, listeners generally can create many
+pipes, which may be open concurrently.
+
+TIP: While it is convenient to think of listeners as "servers", 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 act of "binding" to the address indicated by _url_ is done
+synchronously, including any necessary name resolution.  As a result,
+a failure, such as if the address is already in use, will be returned
+immediately.  However, if the special value `NNG_FLAG_NONBLOCK` is
+supplied in _flags_, then this is done asynchronously; furthermore any
+failure to bind will be periodically reattempted in the background.
+
+TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient,
+it also generally makes diagnosing failures somewhat more difficult.
+
+Because the listener is started immediately, it is generally not possible
+to apply extra configuration; if that is needed applications should consider
+using <<nng_listener_create#,nng_listener_create(3)>> and 
+<<nng_listener_start#,nng_listener_start(3)>> instead.
+
+The created listener will continue to accept new connections, associating
+their pipes with the socket, until either it or the socket _s_ is closed.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EADDRINUSE`:: The address specified by _url_ is already in use.
+`NNG_EADDRINVAL`:: An invalid _url_ was specified.
+`NNG_ECLOSED`:: The socket _s_ is not open.
+`NNG_EINVAL`:: An invalid set of _flags_ was specified.
+`NNG_ENOMEM`:: Insufficient memory is available.
+
+== SEE ALSO
+
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng_dial#,nng_dial(3)>>,
+<<nng_listener_close#,nng_listener_close(3)>>,
+<<nng_listener_create#,nng_listener_create(3)>>
+<<nng_listener_start#,nng_listener_start(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_listener_close.adoc b/docs/nng_listener_close.adoc
new file mode 100644
index 00000000..029322be
--- /dev/null
+++ b/docs/nng_listener_close.adoc
@@ -0,0 +1,56 @@
+= nng_listener_close(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_listener_close - close listener
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listener_close(nng_listener l);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener_close()` function closes the listener _l_.
+This also closes any pipes that have been created by the listener.
+
+Once this function returns, the listener _l_ and any of its resources
+are deallocated.  Therefore it is an error to attempt to access _l_
+after this function has returned.  (Attempts to do so will result in
+`NNG_ECLOSED` errors.)
+
+Listeners are implicitly closed when the socket they are associated with
+is closed.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener.
+
+== SEE ALSO
+
+<<nng_close#,nng_close(3)>>,
+<<nng_listen#,nng_listen(3)>>,
+<<nng_listener_create#,nng_listener_create(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file
diff --git a/docs/nng_listener_create.adoc b/docs/nng_listener_create.adoc
new file mode 100644
index 00000000..ca3dff62
--- /dev/null
+++ b/docs/nng_listener_create.adoc
@@ -0,0 +1,76 @@
+= nng_listener_create(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_listener_create - create listener
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listener_create(nng_listener *listenerp, nng_socket s, const char *url);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener_create()` function creates a newly initialized
+listener, associated with socket _s_, and configured to listen at the
+address specified by _url_, and stores a pointer to at the location
+referenced by _listenerp_.
+
+Listeners are used to accept connections initiated by remote dialers.  An
+incoming connection generally results in a pipe being created and attached
+to the socket _s_.  Unlike dialers, listeners generally can create many
+pipes, which may be open concurrently.
+
+TIP: While it is convenient to think of listeners as "servers", 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!
+
+The listener is not started, but may be further configured with
+the <<nng_listener_setopt#,nng_listener_setopt(3)>> family of
+functions.
+
+Once it is fully configured, the listener may be started using the
+<<nng_listener_start#,nng_listener_start(3)>> function.
+
+TIP: If no specific configuration is required, consider using the
+simpler <<nng_listen#,nng_listen(3)>> function 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_ENOMEM`:: Insufficient memory is available.
+
+== SEE ALSO
+
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng_dialer_create#,nng_dialer_create(3)>>
+<<nng_listen#,nng_listen(3)>>,
+<<nng_listener_close#,nng_listener_close(3)>>,
+<<nng_listener_getopt#,nng_listener_getopt(3)>>,
+<<nng_listener_setopt#,nng_listener_setopt(3)>>,
+<<nng_listener_start#,nng_listener_start(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_listener_getopt.adoc b/docs/nng_listener_getopt.adoc
new file mode 100644
index 00000000..ab1f9cd5
--- /dev/null
+++ b/docs/nng_listener_getopt.adoc
@@ -0,0 +1,110 @@
+= nng_listener_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_listener_getopt - get listener option
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listener_getopt(nng_listener l, const char *opt, void *val,
+    size_t *valszp);
+int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp);
+int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp);
+int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr);
+int nng_listener_setopt_size(nng_listener l, const char *opt, size_t *zp);
+int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener_getopt()` functions are used to retrieve option values for
+the listener _l_. 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 listener _l_.
+
+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_listener_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_listener_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_listener_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_listener_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_listener_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_listener_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 _l_ does not refer to an open listener.
+`NNG_ENOTSUP`:: The option _opt_ is not supported.
+`NNG_EWRITEONLY`:: The option _opt_ is write-only.
+
+== SEE ALSO
+
+<<nng_listen#,nng_listen(3)>>,
+<<nng_listener_create#,nng_listener_create(3)>>
+<<nng_listener_setopt#,nng_listener_setopt(3)>>
+<<nng_getopt#,nng_getopt(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file
diff --git a/docs/nng_listener_setopt.adoc b/docs/nng_listener_setopt.adoc
new file mode 100644
index 00000000..e0f85932
--- /dev/null
+++ b/docs/nng_listener_setopt.adoc
@@ -0,0 +1,108 @@
+= nng_listener_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_listener_setopt - set listener option
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listener_setopt(nng_listener l, const char *opt, const void *val,
+    size_t valsz);
+int nng_listener_setopt_int(nng_listener l, const char *opt, int ival);
+int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur);
+int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr);
+int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z);
+int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str);
+int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener_setopt()` functions are used to configure options for
+the listener _l_. 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 listener _l_.
+
+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_listener_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_listener_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_listener_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_listener_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_listener_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_listener_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_listener_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 listener 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 _l_ does not refer to an open listener.
+`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 listener _l_ is already started.
+
+== SEE ALSO
+
+<<nng_listen#,nng_listen(3)>>,
+<<nng_listener_create#,nng_listener_create(3)>>
+<<nng_listener_getopt#,nng_listener_getopt(3)>>
+<<nng_setopt#,nng_setopt(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file
diff --git a/docs/nng_listener_start.adoc b/docs/nng_listener_start.adoc
new file mode 100644
index 00000000..c034bfab
--- /dev/null
+++ b/docs/nng_listener_start.adoc
@@ -0,0 +1,54 @@
+= nng_listener_start(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_listener_start - start listener
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_listener_start(nng_listener l);
+-----------
+
+== DESCRIPTION
+
+The `nng_listener_start()` function starts the listener _l_.
+
+This causes the listener to start accepting connections from remote
+dialers.  Each new connection results in a pipe, which will be attached
+to the listener's socket.
+
+Once a listener 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 _l_ does not refer to an open listener.
+`NNG_ESTATE`:: The listener _l_ is already started.
+
+== SEE ALSO
+
+<<nng_listen#,nng_listen(3)>>,
+<<nng_listener_create#,nng_listener_create(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
\ No newline at end of file