---
name: "upscli_list_next"
section: "3"
platform: "linux"
package: "nut"
version: "2.8.5-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/upscli_list_next"
---

# upscli\_list\_next(3)

Retrieve 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

The **upscli\_list\_next()** function takes the pointer *ups* to a UPSCONN\_t state structure, and the pointer *query* to an array of *numq* query elements. It performs a read from the network and expects to find either another list item or the end of a list.

You must call [**upscli\_list\_start**(3)](/upscli_list_start/3.md) before calling this function.

This function will return *1* and set values in *numa* and *answer* if a list item is received. If the list is done, it will return *0*, and the values in *numa* and *answer* are undefined.

Calling this function after it returns something other than *1* is undefined behavior.

## QUERY FORMATTING

You may not change the values of *numq* or *query* between the call to [**upscli\_list\_start**(3)](/upscli_list_start/3.md) and the first call to this function. You also may not change the values between calls to this function.

## ANSWER FORMATTING

The contents of *numa* and *answer* work just like a call to [**upscli\_get**(3)](/upscli_get/3.md). The values returned by [**upsd**(8)](/upsd/8.md) are identical to a single item request, so this is not surprising.

## ERROR CHECKING

This function checks the response from [**upsd**(8)](/upsd/8.md) against your query. If the response is not part of the list you have requested, it will return an error code.

When this happens, [**upscli\_upserror**(3)](/upscli_upserror/3.md) will return UPSCLI\_ERR\_PROTOCOL.

## RETURN VALUE

The **upscli\_list\_next()** function returns *1* when list data is present, *0* if the list is finished, or *-1* if an error occurs.

It is possible to have an empty list. The function will return *0* for its first call in that case.

## SEE ALSO

[**upscli\_list\_start**(3)](/upscli_list_start/3.md), [**upscli\_strerror**(3)](/upscli_strerror/3.md), [**upscli\_upserror**(3)](/upscli_upserror/3.md)