UPSCLI_LIST_START(3)

✨ UPSCLI_LIST_START ✨

okay bestie so this is a page from the NUT Manual (that's Network UPS Tools, not the other thing 😭) and it's about upscli_list_start(3) — the function that kicks off a multi-item list pull from a UPS. it's giving very "first step of a two-step" energy and honestly? iconic. 🎀

---

🌸 NAME 🌸

upscli_list_start — Begin multi-item retrieval from a UPS

---

🦋 SYNOPSIS 🦋

#include <upsclient.h>

int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query)

---

💖 DESCRIPTION 💖

so upscli_list_start() takes the pointer ups, which points at a UPSCONN_t state structure, plus the pointer query, which points at an array of numq query elements. it builds a properly-formatted request out of those elements and yeets it straight to upsd(8). 💅

upon success, you — the caller — must call upscli_list_next(3) to actually retrieve the elements of the list. and like, we mean must. failing to retrieve the list will most likely result in the client getting out of sync with the server because of buffered data. and that's not a vibe. 😭

---

👑 USES 👑

this function implements the "LIST" command in the protocol. so basically you can use it to request so many different things from the server. some examples are:

• LIST UPS
• LIST VAR <ups>
• LIST RW <ups>
• LIST CMD <ups>
• LIST ENUM <ups> <var>
• LIST RANGE <ups> <var>

---

🎀 QUERY FORMATTING 🎀

so say you wanna see the list of variables on a UPS called su700. the protocol command would be LIST VAR su700. to start that list with this function, you'd populate query and numq like this:

size_t numq;
const char *query[2];

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

and the best part? all escaping of special characters and quoting of elements with spaces are handled for you inside this function. no cap, you don't gotta do a thing. 🫶

---

🔥 ERROR CHECKING 🔥

this function checks the response from upsd(8) against your query. if it's not starting a list, or it's starting the wrong type of list, it will return an error code. (vibe check: failed 💀)

when this happens, upscli_upserror(3) will return UPSCLI_ERR_PROTOCOL.

---

⭐ RETURN VALUE ⭐

the upscli_list_start() function returns 0 on success, or -1 if an error occurs. simple as that, periodt.

---

🌈 SEE ALSO 🌈

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

---

okay that's the whole page bestie, go forth and list things 💖 this was Network UPS Tools 2.8.5, dated 10/07/2026 — mwah, slay, drink water, and always call upscli_list_next(3) after you start a list. 🧚‍♀️🌸