UPSCLI_READLINE(3)

💜 UPSCLI_READLINE — bestie edition 💜

okay so this is a page from the NUT Manual, and it's literally all about your new fave trio of functions: upscli_readline, upscli_readline_timeout, and upscli_readline_timeout_may_disconnect 🫶

---

✨ NAME ✨

upscli_readline, upscli_readline_timeout, upscli_readline_timeout_may_disconnect — the girlies that read a single response from a UPS 💅 like, one (1) line, that's the whole job, and they ate.

---

🦋 SYNOPSIS 🦋

#include <upsclient.h>
#include <time.h> /* or <sys/time.h> on some platforms */

int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen);

int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen,
        const time_t timeout);

int upscli_readline_timeout_may_disconnect(UPSCONN_t *ups,
        char *buf, size_t buflen, const time_t timeout,
        int may_disconnect);

just look at them. iconic signatures. no notes 💖

---

🌸 DESCRIPTION 🌸

okay so picture this: upscli_readline() and upscli_readline_timeout() both take the pointer ups, which points at a UPSCONN_t state structure — that's your connection's whole vibe holder — and then they receive a single line from the server, and copy up to buflen bytes of that response into the buffer buf. lowkey simple, highkey important 🔥

ngl some parsing happens during reception, like while the string is coming in. in particular, ERR messages from upsd(8) get detected, and when that happens this function will return -1. so yeah, error energy detected = -1, periodt 💀

now the tea on the difference between the three functions 🎀 upscli_readline_timeout() lets the caller decide the amount of time (timeout seconds) after which it should give up and return — you're the main character, you pick the number, slay. whereas upscli_readline() does not offer this freedom 😭 and instead uses the NUT default network timeout, which is 5 seconds. both of these disconnect upon errors, no cap.

and then upscli_readline_timeout_may_disconnect() further allows you to enable or disable such disconnections, so it's giving "options, options, options" ✨ iykyk.

---

⭐ RETURN VALUE ⭐

• upscli_readline() and upscli_readline_timeout() return 0 on success 💖
• or -1 if an error occurs 🙈

that's it, that's the whole glow-up.

---

🌈 SEE ALSO 🌈

• upscli_fd(3)
• upscli_get(3)
• upscli_readline(3)
• upscli_sendline(3)
• upscli_ssl(3)
• upscli_strerror(3)
• upscli_upserror(3)

go read those next bestie, they're all lowkey connected 🧚

---

a lil warning-aside from me to you: remember that upscli_readline() has zero timeout freedom (5 sec default, forever, always) and that both it and upscli_readline_timeout() disconnect upon errors — if you don't want the disconnect, upscli_readline_timeout_may_disconnect() is your girl 💅

---

omg and before i forget — this whole page is from Network UPS Tools 2.8.5, dated 06/21/2026, and that's the official NUT Manual energy right there 👑 stay safe out there, keep your connections ssl'd and your buffers sized 💜✨🎀