nut-debian/docs/man/upscli_list_next.txt

UPSCLI_LIST_NEXT(3)
===================

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 linkman: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.

QUERY FORMATTING
----------------

You may not change the values of 'numq' or 'query' between the
call to linkman:upscli_list_start[3] 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
linkman:upscli_get[3].  The values returned by linkman:upsd[8] are
identical to a single item request, so this is not surprising.

ERROR CHECKING
--------------

This function checks the response from linkman: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, linkman:upscli_upserror[3] 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
--------

linkman:upscli_list_start[3],
linkman:upscli_strerror[3], linkman:upscli_upserror[3]