nng_dial(3)

# nng_dial(3) Manual Page

## 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.

| 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.

| 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)