diff options
Diffstat (limited to 'docs/man/nng_dial.3.adoc')
| -rw-r--r-- | docs/man/nng_dial.3.adoc | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/docs/man/nng_dial.3.adoc b/docs/man/nng_dial.3.adoc new file mode 100644 index 00000000..c2044dfb --- /dev/null +++ b/docs/man/nng_dial.3.adoc @@ -0,0 +1,93 @@ += nng_dial(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== 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 +<<nng_dialer.5#,`nng_dialer`>> object, +associated with socket _s_, and configured to listen at the +address specified by _url_, and starts it. +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 <<nng_pipe.5#,pipe>>, +add it to the socket, and then wait for that pipe to be closed. +When the pipe is closed, the dialer attempts to re-establish the connection. +Dialers 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.7#,_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.3#,`nng_dialer_create()`>> and +<<nng_dialer_start.3#,`nng_dialer_start()`>> 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.3#,nng_dialer_close(3)>>, +<<nng_dialer_create.3#,nng_dialer_create(3)>> +<<nng_dialer_start.3#,nng_dialer_start(3)>>, +<<nng_listen.3#,nng_listen(3)>>, +<<nng_strerror.3#,nng_strerror(3)>>, +<<nng_dialer.5#,nng_dialer(5)>>, +<<nng_pipe.5#,nng_pipe(5)>>, +<<nng.7#,nng(7)>> |