UPSCLI_CONNECT(3)

💖 UPSCLI_CONNECT(3) — the NUT Manual, but make it a group chat 💖

okay bestie, we're in the UPSCLI_CONNECT part of the NUT manual today and honestly? it's giving ✨networking✨. two functions, one job: get you a live TCP hookup to an upsd data server. let's get into it 🫶

---

🌸 NAME 🌸

upscli_connect, upscli_tryconnect — open a connection to a NUT upsd data server. that's the whole vibe. literally that's it 💅

---

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

look at them. two little functions. so cute. so powerful. no cap 🎀

---

🦋 DESCRIPTION 🦋

so upscli_connect() takes that pointer ups — which points at a UPSCONN_t state structure, that's your connection's whole personality holder — and it opens a TCP connection to the host on the given port. iconic behavior, honestly 🌈

by default this makes a blocking connection attempt. and when we say blocking, we mean it sits there until the system transport layer times out the underlying select(2) call. like it will simply wait. main character energy but make it patient 💀

good news tho: you can configure a program-wide default timeout for this method using upscli_set_default_connect_timeout(3) or upscli_init_default_connect_timeout(3). and if you want an explicit, operation-specific timeout instead of a global vibe? that's exactly what upscli_tryconnect() is for, bestie. use that one 🫶

Note 📌 as part of general initialization, both the upscli_init(3) function or the first call to upscli_connect() can call the upscli_init_default_connect_timeout(3) method — but only if it was never used before. why does this matter? because it lets unmodified (legacy) NUT clients consistently benefit from the presence of the NUT_DEFAULT_CONNECT_TIMEOUT environment variable, so that upscli_connect(3) attempts are not blocking (as per default). yes, that's a lot of words. yes, it's important. slay ✨

okay now flags. this one's a choose-your-own-adventure:

• it can be UPSCLI_CONN_TRYSSL — try a SSL connection 👀
• or it can be UPSCLI_CONN_REQSSL — require a SSL connection, no negotiating 🔥

and introduced in version 2.7, there's an extra flag in the mix: UPSCLI_CONN_CERTVERIF. this one verifies the signature offered during the SSL handshake. you should use it together with upscli_init(3) and/or upscli_add_host_cert(3) calls before connecting, so you can define a CA certificate to verify against. do the setup first, then connect. order matters, bestie, fr fr 💜

if SSL mode is required, this function will only return successfully if it's able to establish a SSL connection with the server. periodt. possible reasons it might fail include:

• no SSL support on the server 🚫
• upsclient itself hasn't been compiled with SSL support 🚫

⚠️ real talk warning ⚠️ you must call upscli_disconnect(3) when you're finished with a connection. if you don't, your program will slowly leak memory and file descriptors. not a vibe. not cute. not the moment. close your connections, bestie 😭

---

👑 RETURN VALUE 👑

upscli_connect() modifies the UPSCONN_t structure and returns:

• 0 on success 🎉
• -1 if an error occurs 💀

that's it. that's the whole scoring system.

---

🌟 SEE ALSO 🌟

go read these next, i'm obsessed with them:

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

---

and that's the page!! this was Network UPS Tools 2.8.5, dated 10/07/2026, and it lives under UPSCLI_CONNECT(3) in the NUT manual. thanks for coming to my ted talk, go call upscli_disconnect(3) when you're done, ily, bye 💖✨🎀