From 72757bd87a8c3801137348dd026901032b8b623d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 16 Feb 2018 10:29:53 -0800 Subject: Add nng_listen* man pages. --- docs/libnng.adoc | 25 ++++++++-- docs/nng_close.adoc | 8 +-- docs/nng_listen.adoc | 84 ++++++++++++++++++++++++++++++++ docs/nng_listener_close.adoc | 56 +++++++++++++++++++++ docs/nng_listener_create.adoc | 76 +++++++++++++++++++++++++++++ docs/nng_listener_getopt.adoc | 110 ++++++++++++++++++++++++++++++++++++++++++ docs/nng_listener_setopt.adoc | 108 +++++++++++++++++++++++++++++++++++++++++ docs/nng_listener_start.adoc | 54 +++++++++++++++++++++ 8 files changed, 512 insertions(+), 9 deletions(-) create mode 100644 docs/nng_listen.adoc create mode 100644 docs/nng_listener_close.adoc create mode 100644 docs/nng_listener_create.adoc create mode 100644 docs/nng_listener_getopt.adoc create mode 100644 docs/nng_listener_setopt.adoc create mode 100644 docs/nng_listener_start.adoc (limited to 'docs') 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. |=== -|<>|close a socket -|<>|create and start a dialer -|<>|get a socket option -|<>|create and start a listener +|<>|close socket +|<>|create and start dialer +|<>|get socket option +|<>|create and start listener |<>|receive data |<>|send data -|<>|set a socket option +|<>|set socket option +|=== + +=== Connection Management + +The following functions are used with either listeners, or dialers. +Listeners accept incoming connection requets, and dialers make them. + +|=== +|<>|create and start dialer +|<>|create and start listener +|<>|close listener +|<>|create listener +|<>|get listener option +|<>|set listener option +|<>|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 -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 + +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 <> +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 <> and +<> 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 + +<>, +<>, +<>, +<> +<>, +<> + +== 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 + +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 + +<>, +<>, +<> +<>, +<> + +== 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 + +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 <> +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 <> family of +functions. + +Once it is fully configured, the listener may be started using the +<> function. + +TIP: If no specific configuration is required, consider using the +simpler <> 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 + +<>, +<> +<>, +<>, +<>, +<>, +<>, +<> + +== 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 + +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 <> 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 + +<>, +<> +<> +<>, +<>, +<> + +== 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 + +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 <> 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 +(<>) 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 + +<>, +<> +<> +<>, +<>, +<> + +== 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 + +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 + +<>, +<> +<>, +<> + +== COPYRIGHT + +{copyright} \ No newline at end of file -- cgit v1.2.3-70-g09d2