UPSCLI_CONNECT(3)

🎀 NAME 🎀

Okay bestie, welcome to UPSCLI_CONNECT(3) from the NUT Manual 💖. This page is all about upscli_connect, upscli_tryconnect — the functions that open a connection to a NUT upsd data server. Slay.

✨ SYNOPSIS ✨

Here's the exact code vibe:

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

So upscli_connect() takes the pointer ups to a UPSCONN_t state structure and opens a TCP connection to the host on the given port. Main character behavior, honestly.

By default this makes a blocking connection attempt (until the system transport layer times out the underlying select(2) call). A program-wide default timeout for this method can be configured with the upscli_set_default_connect_timeout(3) or upscli_init_default_connect_timeout(3) methods. For operations with explicit operation-specific timeout please use the upscli_tryconnect() method instead. No cap.

Note — As part of general initialization, both the upscli_init(3) function or the first call to upscli_connect() function, can call the upscli_init_default_connect_timeout(3) 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) 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. Periodt.

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) and/or upscli_add_host_cert(3) calls before connecting in order to define a CA certificate with which to verify. Obsessed with a verified vibe check 🔥.

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. That's the tea 😭.

⚠️ You must call upscli_disconnect(3) when finished with a connection, or your program will slowly leak memory and file descriptors. Not me leaving a connection open and leaking like a disaster 🫶 — literally call upscli_disconnect(3).

🌈 RETURN VALUE 🌈

The upscli_connect() function modifies the UPSCONN_t structure and returns 0 on success, or -1 if an error occurs. That's it bestie — 0 means slay, -1 means something went off.

👑 SEE ALSO 👑

Go give these iconic pages a read, iykyk:

• upscli_disconnect(3)
• upscli_fd(3)
• upscli_init(3)
• upscli_splitaddr(3)
• upscli_splitname(3)
• upscli_ssl(3)
• upscli_strerror(3)
• upscli_get_default_connect_timeout(3)
• upscli_set_default_connect_timeout(3)
• upscli_init_default_connect_timeout(3)
• upscli_upserror(3)

xoxo bestie, this page is from Network UPS Tools 2.8.5, dated 06/21/2026 💖✨💅