diff options
| -rw-r--r-- | docs/libnng.adoc | 5 | ||||
| -rw-r--r-- | docs/nng_dial.adoc | 91 | ||||
| -rw-r--r-- | docs/nng_dialer_close.adoc | 56 | ||||
| -rw-r--r-- | docs/nng_dialer_create.adoc | 78 | ||||
| -rw-r--r-- | docs/nng_dialer_getopt.adoc | 109 | ||||
| -rw-r--r-- | docs/nng_dialer_setopt.adoc | 108 | ||||
| -rw-r--r-- | docs/nng_dialer_start.adoc | 78 |
7 files changed, 525 insertions, 0 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 60e9fad4..3262bf38 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -56,6 +56,11 @@ Listeners accept incoming connection requets, and dialers make them. |=== |<<nng_dial#,nng_dial(3)>>|create and start dialer +|<<nng_dialer_close#,nng_dialer_close(3)>>|close dialer +|<<nng_dialer_create#,nng_dialer_create(3)>>|create dialer +|<<nng_dialer_getopt#,nng_dialer_getopt(3)>>|get dialer option +|<<nng_dialer_setopt#,nng_dialer_setopt(3)>>|set dialer option +|<<nng_dialer_start#,nng_dialer_start(3)>>|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 diff --git a/docs/nng_dial.adoc b/docs/nng_dial.adoc new file mode 100644 index 00000000..f3cff465 --- /dev/null +++ b/docs/nng_dial.adoc @@ -0,0 +1,91 @@ += nng_dial(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_dial - create and start dialer + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags); +----------- + +== DESCRIPTION + +The `nng_dialer()` function creates a newly initialized +dialer, associated with socket _s_, and configured to listen at the +address specified by _url_. If the value of _dp_ is not `NULL`, then +the newly created dialer is stored at the address indicated by _dp_. + +Dialers initiate a remote connection to a listener. Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. When the pipe is closed, +they will re-initiate the connection. Dialer's will also periodically +retry a connection automatically if an attempt to connect asynchronously +fails. + +TIP: While it is convenient to think of dialers as "clients", 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 first attempt to connect to the address indicated by _url_ 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. + +Because the dialer is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using <<nng_dialer_create#,nng_dialer_create(3)>> and +<<nng_dialer_start#,nng_dialer_start(3)>> 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_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_EUNREACHABLE`:: The remote address is not reachable. + +== SEE ALSO + +<<nng_dialer_close#,nng_dialer_close(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_dialer_start#,nng_dialer_start(3)>>, +<<nng_listen#,nng_listen(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_dialer_close.adoc b/docs/nng_dialer_close.adoc new file mode 100644 index 00000000..f4f5d76b --- /dev/null +++ b/docs/nng_dialer_close.adoc @@ -0,0 +1,56 @@ += nng_dialer_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_dialer_close(nng_dialer d); +----------- + +== DESCRIPTION + +The `nng_dialer_close()` function closes the listener _d_. +This also closes any pipe that has been created by the dialer. + +Once this function returns, the dialer _d_ and any of its resources +are deallocated. Therefore it is an error to attempt to access _d_ +after this function has returned. (Attempts to do so will result in +`NNG_ECLOSED` errors.) + +Dialers 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 _d_ does not refer to an open listener. + +== SEE ALSO + +<<nng_close#,nng_close(3)>>, +<<nng_dial#,nng_dial(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright}
\ No newline at end of file diff --git a/docs/nng_dialer_create.adoc b/docs/nng_dialer_create.adoc new file mode 100644 index 00000000..d65dd9e4 --- /dev/null +++ b/docs/nng_dialer_create.adoc @@ -0,0 +1,78 @@ += nng_dialer_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_dialer_create - create dialer + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_create(nng_dialer *dialerp, nng_socket s, const char *url); +----------- + +== DESCRIPTION + +The `nng_dialer_create()` function creates a newly initialized +dialer, associated with socket _s_, and configured to connect to the +address specified by _url_, and stores a pointer to at the location +referenced by _dialerp_. + +Dialers initiate a remote connection to a listener. Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. When the pipe is closed, +they will re-initiate the connection. Dialer's will also periodically +retry a connection automatically if an attempt to connect asynchronously +fails. + +TIP: While it is convenient to think of dialers as "clients", 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 dialer is not started, but may be further configured with +the <<nng_dialer_setopt#,nng_dialer_setopt(3)>> family of +functions. + +Once it is fully configured, the dialer may be started using the +<<nng_dialer_start#,nng_dialer_start(3)>> function. + +TIP: If no specific configuration is required, consider using the +simpler <<nng_dial#,nng_dial(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_dial#,nng_dial(3)>>, +<<nng_dialer_close#,nng_dialer_close(3)>>, +<<nng_dialer_getopt#,nng_dialer_getopt(3)>>, +<<nng_dialer_setopt#,nng_dialer_setopt(3)>>, +<<nng_dialer_start#,nng_dialer_start(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} 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 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 diff --git a/docs/nng_dialer_start.adoc b/docs/nng_dialer_start.adoc new file mode 100644 index 00000000..b6c6306d --- /dev/null +++ b/docs/nng_dialer_start.adoc @@ -0,0 +1,78 @@ += nng_dialer_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_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 +it's 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#,nng_dial(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright}
\ No newline at end of file |