The \fBupscli_list_start()\fR function takes the pointer \fIups\fR to a UPSCONN_t state structure, and the pointer \fIquery\fR to an array of \fInumq\fR query elements\&. It builds a properly\-formatted request from those elements and transmits it to \fBupsd\fR(8)\&.
.sp
Upon success, the caller must call \fBupscli_list_next\fR(3) to retrieve the elements of the list\&. Failure to retrieve the list will most likely result in the client getting out of sync with the server due to buffered data\&.
.SH"USES"
.sp
This function implements the "LIST" command in the protocol\&. As a result, you can use it to request many different things from the server\&. Some examples are:
To see the list of variables on a UPS called \fIsu700\fR, the protocol command would be LIST VAR su700\&. To start that list with this function, you would populate query and numq as follows:
All escaping of special characters and quoting of elements with spaces are handled for you inside this function\&.
.SH"ERROR CHECKING"
.sp
This function checks the response from \fBupsd\fR(8) against your query\&. If it is not starting a list, or is starting the wrong type of list, it will return an error code\&.
.sp
When this happens, \fBupscli_upserror\fR(3) will return UPSCLI_ERR_PROTOCOL\&.
.SH"RETURN VALUE"
.sp
The \fBupscli_list_start()\fR function returns 0 on success, or \-1 if an error occurs\&.
