upscli_list_next - Man Page

        #include <upsclient​.h>

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

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) 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​.

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​. You also may not change the values between calls to this function​.

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 this is not surprising​.

This function checks the response from upsd(8) 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) will return UPSCLI_ERR_PROTOCOL​.

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​.

upscli_list_start(3), upscli_strerror(3), upscli_upserror(3)

nut(7), upsclient(3), upscli_get(3), upscli_list_start(3).