---
name: "upscli_connect"
section: "3"
platform: "linux"
package: "nut"
version: "2.8.5-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/upscli_connect"
---

# upscli\_connect(3)

Open a connection to a NUT upsd data server

## NAME

upscli\_connect, upscli\_tryconnect - Open a connection to a NUT upsd data server

## SYNOPSIS

```
        #include <upsclient.h>
        /* Open a connection to a NUT upsd data server (blocking by default) */
        int upscli_connect(UPSCONN_t *ups, const char *host, uint16_t port, int flags);
        /* Open a connection to a NUT upsd data server with specified timeout */
        int upscli_tryconnect(UPSCONN_t *ups, const char *host, uint16_t port, int flags,
                struct timeval * timeout);
```

## DESCRIPTION

The **upscli\_connect()** function takes the pointer *ups* to a UPSCONN\_t state structure and opens a TCP connection to the *host* on the given *port*.

By default this makes a blocking connection attempt (until the system transport layer times out the underlying [**select**(2)](/select/2.md) call). A program-wide default timeout for this method can be configured with the [**upscli\_set\_default\_connect\_timeout**(3)](/upscli_set_default_connect_timeout/3.md) or [**upscli\_init\_default\_connect\_timeout**(3)](/upscli_init_default_connect_timeout/3.md) methods. For operations with explicit operation-specific timeout please use the **upscli\_tryconnect()** method instead.

**Note**\

As part of general initialization, both the [**upscli\_init**(3)](/upscli_init/3.md) function or the first call to **upscli\_connect()** function, can call the [**upscli\_init\_default\_connect\_timeout**(3)](/upscli_init_default_connect_timeout/3.md) method (if it was never used before): this allows unmodified (legacy) NUT clients to consistently benefit from presence of the NUT\_DEFAULT\_CONNECT\_TIMEOUT environment variable for [**upscli\_connect**(3)](/upscli_connect/3.md) attempts to be not blocking (as per default).

*flags* may be either UPSCLI\_CONN\_TRYSSL to try a SSL connection, or UPSCLI\_CONN\_REQSSL to require a SSL connection.

Introduced in version 2.7, an additional flag UPSCLI\_CONN\_CERTVERIF now exists to verify the signature offered during the SSL handshake. This flag should be used in conjunction with [**upscli\_init**(3)](/upscli_init/3.md) and/or [**upscli\_add\_host\_cert**(3)](/upscli_add_host_cert/3.md) calls before connecting in order to define a CA certificate with which to verify.

If SSL mode is required, this function will only return successfully if it is able to establish a SSL connection with the server. Possible reasons for failure include no SSL support on the server, and if **upsclient** itself hasn’t been compiled with SSL support.

You must call [**upscli\_disconnect**(3)](/upscli_disconnect/3.md) when finished with a connection, or your program will slowly leak memory and file descriptors.

## RETURN VALUE

The **upscli\_connect()** function modifies the UPSCONN\_t structure and returns *0* on success, or *-1* if an error occurs.

## SEE ALSO

[**upscli\_disconnect**(3)](/upscli_disconnect/3.md), [**upscli\_fd**(3)](/upscli_fd/3.md), [**upscli\_init**(3)](/upscli_init/3.md), [**upscli\_splitaddr**(3)](/upscli_splitaddr/3.md), [**upscli\_splitname**(3)](/upscli_splitname/3.md), [**upscli\_ssl**(3)](/upscli_ssl/3.md), [**upscli\_strerror**(3)](/upscli_strerror/3.md), [**upscli\_get\_default\_connect\_timeout**(3)](/upscli_get_default_connect_timeout/3.md), [**upscli\_set\_default\_connect\_timeout**(3)](/upscli_set_default_connect_timeout/3.md), [**upscli\_init\_default\_connect\_timeout**(3)](/upscli_init_default_connect_timeout/3.md), [**upscli\_upserror**(3)](/upscli_upserror/3.md)