UPSCLI_GET(3)

💖 UPSCLI_GET(3) — the NUT Manual, but make it cute 💖

okay bestie, welcome to UPSCLI_GET(3) from the NUT Manual ✨ this is the page where we learn how to ask the UPS server for stuff and get an answer back. it's giving "please tell me ur secrets, upsd" 🫶

---

✨ NAME ✨

upscli_get — Retrieve data from an UPS 💅

---

🌸 SYNOPSIS 🌸

#include <upsclient.h>

int upscli_get(
        UPSCONN_t *ups,
        size_t numq,
        const char **query,
        size_t *numa,
        char ***answer)

---

🦋 DESCRIPTION 🦋

so like, upscli_get() takes the pointer ups — that's ur pointer to a UPSCONN_t state structure, the main character of the connection 🎀 — and the pointer query, which points at an array of numq query elements. it takes all those little elements, builds a properly-formatted request out of them, and yeets it over to upsd(8). no cap. 🚀

and when it works? slay. 💖 the response gets split into separate components for u. a pointer to those components comes back in answer. and the number of usable answer components comes back in numa. iconic.

---

🔥 USES 🔥

this function implements the "GET" command in the NUT protocol. which means — and this is the fun part — u can use it to request SO many different things from the server. the range?? unmatched.

some examples are:

• GET NUMLOGINS <ups>
• GET UPSDESC <ups>
• GET VAR <ups> <var>
• GET TYPE <ups> <var>
• GET DESC <ups> <var>
• GET CMDDESC <ups> <cmd>

---

🎀 QUERY FORMATTING 🎀

say u wanna generate a request for GET NUMLOGINS su700. bestie, u would populate query and numq like this:

size_t numq;
const char *query[2];

query[0] = "NUMLOGINS";
query[1] = "su700";
numq = 2;

and here's the best part: all escaping of special characters and all quoting of elements with spaces is handled for u inside this function. u literally don't have to think about it. periodt. 💅✨

---

🌈 ANSWER FORMATTING 🌈

the raw response from upsd to that query above would be NUMLOGINS su700 1.

and since this gets split up for u, the values work out like this:

size_t numa;

numa = 3;
answer[0] = "NUMLOGINS"
answer[1] = "su700"
answer[2] = "1"

📌 notice that the value which u actually seek typically starts at answer[numq]. iykyk.

---

💀 ERROR CHECKING 💀

this function will check ur query against the response from the upsd(8) data server. it's like a vibe check but for protocol data.

for example, if u send "VAR" "su700" "ups.status", it will expect to see those at the beginning of the response. like, be there or be square.

if the results from upsd do not pass this case-insensitive test against ur request, this function will return an error. 😭 and when that happens? upscli_upserror(3) will return UPSCLI_ERR_PROTOCOL.

---

🧚 ANSWER ARRAY LIFETIME 🧚

okay this part is IMPORTANT, listen up bestie 🫶

the pointers contained within the answer array are only valid until the next call to an upsclient function which references them. if u need to use data from multiple calls, u must copy it somewhere else first. no borrowing without copying, that's the rule.

the answer array and its elements may change locations, so u must not rely on previous addresses. u must only use the addresses which were returned by the most recent call. u also must not attempt to use more than numa elements in answer. such behavior is undefined, and may yield bogus data or a crash. 💀 pls don't.

the array will be deleted after calling upscli_disconnect(3). any access after that point is also undefined. so like… don't. 🙈

---

👑 RETURN VALUE 👑

upscli_get() returns 0 on success, or -1 if an error occurs. simple. clean. iconic.

if upsd disconnects, u may need to handle or ignore SIGPIPE in order to prevent ur program from terminating the next time that the library writes to the disconnected socket. 😭 yes really, that's a whole thing.

the following code in ur initialization function will allow the upscli_get() call to return an error in that case:

#include <signal.h>
...
signal (SIGPIPE, SIG_IGN);
...

---

⭐ SEE ALSO ⭐

• upscli_list_start(3)
• upscli_list_next(3)
• upscli_strerror(3)
• upscli_upserror(3)

---

and that's the whole page, bestie!! 🌸💖 this was Network UPS Tools 2.8.5, dated 10/07/2026, and it lives in the UPSCLI_GET(3) era of ur life. go forth and GET responsibly. mwah 💅✨🎀