upscli_list_start - Man Page

        #include <upsclient​.h>

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

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

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>

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

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

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

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

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