UPSCLI_READLINE(3)

✨ UPSCLI_READLINE — bestie, let's read ONE line from the UPS 💖

okay so this is the UPSCLI_READLINE(3) page from the NUT Manual, and it's literally just three little functions that grab a single response line from a UPS. no cap. let's get into it 🦋

---

🌸 NAME 🌸

upscli_readline, upscli_readline_timeout, upscli_readline_timeout_may_disconnect — Read a single response from a UPS ✨

---

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

psst — that <time.h> include is like, <sys/time.h> on some platforms instead, iykyk 🙈

---

💅 DESCRIPTION 💅

so. the way that upscli_readline() and upscli_readline_timeout() work is: you hand them ups, which is a pointer to a UPSCONN_t state structure, they receive a single line from the server, and then they copy up to buflen bytes of that response into the buffer buf. that's the whole vibe. 🫶

and not me mentioning this — some parsing happens while it's receiving, okay?? specifically, ERR messages from upsd(8) get detected, and when that happens this function will return -1. so watch out bestie 😭

now the difference between the three, because this is the part everyone asks about:

• upscli_readline_timeout() — lets you (the caller) decide the amount of time (timeout seconds) after which it should give up and return. so much freedom, we love that for you 👑
• upscli_readline() — does not offer this freedom, and just uses the NUT default network timeout, which is 5 seconds. she's set in her ways fr fr 💀
• both of those two disconnect upon errors. yes, literally, they will hang up on you.
• upscli_readline_timeout_may_disconnect() — goes further and lets you enable or disable such disconnections with the may_disconnect argument. iconic behaviour, honestly ✨

---

🌈 RETURN VALUE 🌈

upscli_readline() and upscli_readline_timeout() return 0 on success 🎉, or -1 if an error occurs 😭.

---

🦋 SEE ALSO 🦋

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

---

and that's the whole page, bestie, you ate 💖

this was Network UPS Tools version 2.8.5, dated 10/07/2026 — go forth and read those lines, main character 🌟💅🎀