UPSCLI_LIST_NEXT(3)

✨ UPSCLI_LIST_NEXT ✨

okay bestie, so this is upscli_list_next(3) from the NUT Manual (Network UPS Tools), and it's literally the lil function that goes and grabs list items from a UPS 💖

---

🌸 NAME 🌸

upscli_list_next — Retrieve list items from a UPS 👑

---

🎀 SYNOPSIS 🎀

#include <upsclient.h>

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

---

💅 DESCRIPTION 💅

so like. upscli_list_next() takes the pointer ups (which points at a UPSCONN_t state structure) and the pointer query (an array of numq query elements). Then it does a read from the network and is like "okay, is this another list item or are we done here?" 🌈

🚨 real talk: you must call upscli_list_start(3) before you call this function. no skipping, no shortcuts, periodt.

Here's the vibe check on what it returns:

• if a list item comes back — it returns 1 and sets values in numa and answer ✅
• if the list is finished — it returns 0, and ngl, the values in numa and answer are undefined at that point 🙈

💀 and this one matters: calling this function after it returns something other than 1 is undefined behavior. not in a cute way. in a "why would you do that" way.

---

🦋 QUERY FORMATTING 🦋

You may not change the values of numq or query between the call to upscli_list_start(3) and the first call to this function. 🫶

And you also may not change the values between calls to this function. so like, set it and leave it alone bestie, it's giving "commitment issues are not the move here." ✨

---

⭐ ANSWER FORMATTING ⭐

The contents of numa and answer work just like a call to upscli_get(3). 💜

The values returned by upsd(8) are identical to a single item request — so honestly? not surprising at all. iconic consistency, we love to see it. 👑

---

🔥 ERROR CHECKING 🔥

This function checks the response from upsd(8) against your query. If the response isn't part of the list you requested, it's gonna return an error code. 😭

When that happens, upscli_upserror(3) will return UPSCLI_ERR_PROTOCOL.

---

💖 RETURN VALUE 💖

upscli_list_next() returns:

• 1 when list data is present ✨
• 0 if the list is finished 🎀
• -1 if an error occurs 💀

And psst — it is possible to have an empty list! In that case the function will return 0 on its very first call. no cap. 🙈

---

🌈 SEE ALSO 🌈

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

---

okay that's the whole thing, you ate that reading session fr fr 💅

this lil masterpiece is from Network UPS Tools 2.8.5, dated 10/07/2026 — go off, NUT team 👑