# UPSCLI_LIST_START(3)

## NAME

upscli_list_start - Begin multi-item retrieval from a UPS

## SYNOPSIS

            #include <upsclient.h>

            int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query)

## DESCRIPTION

The upscli_list_start() function takes the pointer ups to a `UPSCONN_t` state structure, and the pointer query to an array of numq query elements. It builds a properly-formatted request from those elements and transmits it to upsd(8).

Upon success, the caller must call upscli_list_next(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.

## USES

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:

- LIST UPS

- LIST VAR <ups>

- LIST RW <ups>

- LIST CMD <ups>

- LIST ENUM <ups> <var>

- LIST RANGE <ups> <var>

## QUERY FORMATTING

To see the list of variables on a UPS called su700, the protocol command would be `LIST VAR su700`. To start that list with this function, you would populate query and numq as follows:

            size_t numq;
            const char *query[2];

            query[0] = "VAR";
            query[1] = "su700";
            numq = 2;

All escaping of special characters and quoting of elements with spaces are handled for you inside this function.

## ERROR CHECKING

This function checks the response from upsd(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.

When this happens, upscli_upserror(3) will return `UPSCLI_ERR_PROTOCOL`.

## RETURN VALUE

The upscli_list_start() function returns 0 on success, or -1 if an error occurs.

## SEE ALSO

upscli_fd(3), upscli_get(3), upscli_readline(3), upscli_sendline(3), upscli_ssl(3), upscli_strerror(3), upscli_upserror(3)