UPSCLI_INIT_DEFAULT_(3)

💅 UPSCLI_INIT_DEFAULT_(3) — the upsclient timeout glow-up

okay so bestie, before we even start: this is from the NUT Manual, page UPSCLI_INIT_DEFAULT_(3), and it's genuinely one of those little functions that fixes a 20-year-old oopsie. let's get into it 🫶

---

✨ NAME ✨

upscli_init_default_connect_timeout — sets up the upsclient module's side of the default timeout for initial connections. basically: how long should we wait before giving up on a host that's ghosting us 👻

---

🎀 SYNOPSIS 🎀

#include <upsclient.h>

int upscli_init_default_connect_timeout(
        const char *cli_secs,
        const char *config_secs,
        const char *default_secs);

---

🌸 DESCRIPTION 🌸

so upscli_init_default_connect_timeout() initializes the upsclient module aspect of the default connection timeout for upscli_connect(3). and ngl, that matters more than it sounds — it's important when, like, upsc(8) scripting or upsmon(8) configuration is pointing at unresponsive hosts, or when host name resolution is lagging, etc. etc. 💀

fr fr: by default, upscli_connect(3) blocks indefinitely in its attempts to connect — or until the system transport layer interrupts that attempt. no cap, it will just sit there forever. iconic in a bad way.

🦋 where the value comes from

it populates the value from different sources — mostly C strings that represent a floating-point non-negative number. invalid parsing gets logged and may impact the return value, bestie. any or all of them may be NULL to skip, and they're checked in a specific order (last valid hit wins):

1. built-in 0, meaning indefinitely blocking (the NUT default for this method over at least 20 years 🧓);
2. the number from default_secs, as a particular NUT or third-party client program's built-in preferred (low-priority) default;
3. the number from the NUT_DEFAULT_CONNECT_TIMEOUT environment variable, as a site-local preference (generally pre-set in nut.conf(5));
4. the number from config_secs, as a particular NUT or third-party client program's configuration file default;
5. the number from cli_secs, as a particular NUT or third-party client program's setting from the command line (highest priority 👑).

internally, it calls upscli_set_default_connect_timeout(3) for most of the string related processing. that's the girl doing the actual work behind the scenes, periodt.

💜 the tracking bit (this is the good part)

the upsclient module tracks whether upscli_init_default_connect_timeout() was called and succeeded, so it can call it once (if it was never used) from the upscli_connect(3) or upscli_init(3) methods. why? so unmodified (legacy) NUT clients get to consistently benefit from the NUT_DEFAULT_CONNECT_TIMEOUT environment variable just existing. literally a glow-up for code that never asked for one ✨

and don't worry — this tracking does not preclude programs from explicitly calling the method any amount of times. call it 47 times if that's your vibe, we won't judge 💅

---

🔥 RETURN VALUE 🔥

• 0 on success — either because all the strings were NULL (so the built-in default gets applied), or because at least one of the strings that were set was valid and its value got applied. slay.
• -1 if an error occurs — meaning at least one string was not NULL, and none of the strings was valid. 😭

---

⭐ SEE ALSO ⭐

• upscli_connect(3)
• upscli_tryconnect(3)
• upscli_set_default_connect_timeout(3)
• upscli_get_default_connect_timeout(3)
• upscli_init(3)

---

💖 tiny reminder, bestie: that indefinite blocking behaviour is the default, so if you're pointing at a flaky host and nothing happens for, like, ever — this function is the one you're looking for.

okay that's the whole page, go forth and set your timeouts 🌈

Network UPS Tools 2.8.5 · 06/21/2026 — mwah, that's a wrap, see u in the next manpage 🎀🦋✨