Imported Upstream version 2.6.0

docs/man/upscli_list_next.txt

@@ -0,0 +1,70 @@
+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, int numq, const char **query,
+			int *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]