Provided by: libnng-dev_1.9.0-1_amd64 bug

NAME

       nng_dial - create and start dialer

SYNOPSIS

           #include <nng/nng.h>

           int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags);

DESCRIPTION

       The nng_dial() function creates a newly initialized nng_dialer object, associated with
       socket s, and configured to dial 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 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 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()
       and 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 or an invalid url 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_create(3) nng_dialer_start(3), nng_listen(3),
       nng_strerror(3), nng_dialer(5), nng_pipe(5), nng(7)

                                            2024-10-11                                NNG_DIAL(3)