SYNOPSIS

       #include <upsclient.h>

       int upscli_list_start(UPSCONN *ups, int numq, const char **query)

DESCRIPTION

       The  upscli_list_start()  function  takes  the pointer ups to a UPSCONN
       state structure, and the pointer query to an array of numq  query  ele-
       ments.   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>

QUERY FORMATTING

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

            int numq;
            const char *query[2];

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

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

ERROR CHECKING

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