upscli_get - Man Page

        #include <upsclient​.h>

        int upscli_get(
                UPSCONN_t *ups,
                size_t numq,
                const char **query,
                size_t *numa,
                char ***answer)

The upscli_get() 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 response will be split into separate components​. A pointer to those components will be returned in answer​. The number of usable answer components will be returned in numa​.

This function implements the "GET" command in the NUT protocol​. As a result, you can use it to request many different things from the server​.

Some examples are:

• GET NUMLOGINS <ups>
• GET UPSDESC <ups>
• GET VAR <ups> <var>
• GET TYPE <ups> <var>
• GET DESC <ups> <var>
• GET CMDDESC <ups> <cmd>

To generate a request for GET NUMLOGINS su700, you would populate query and numq as follows:

        size_t numq;
        const char *query[2];

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

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

The raw response from upsd to the above query would be NUMLOGINS su700 1​.

Since this is split up for you, the values work out like this:

        size_t numa;

        numa = 3;
        answer[0] = "NUMLOGINS"
        answer[1] = "su700"
        answer[2] = "1"

Notice that the value which you seek typically starts at answer[numq]​.

This function will check your query against the response from upsd(8) data server​.

For example, if you send "VAR" "su700" "ups​.status", it will expect to see those at the beginning of the response​.

If the results from upsd do not pass this case-insensitive test against your request, this function will return an error​. When this happens, upscli_upserror(3) will return UPSCLI_ERR_PROTOCOL​.

The pointers contained within the answer array are only valid until the next call to an upsclient function which references them​. If you need to use data from multiple calls, you must copy it somewhere else first​.

The answer array and its elements may change locations, so you must not rely on previous addresses​. You must only use the addresses which were returned by the most recent call​. You also must not attempt to use more than numa elements in answer​. Such behavior is undefined, and may yield bogus data or a crash​.

The array will be deleted after calling upscli_disconnect(3)​. Any access after that point is also undefined​.

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

If upsd disconnects, you may need to handle or ignore SIGPIPE in order to prevent your program from terminating the next time that the library writes to the disconnected socket​.

The following code in your initialization function will allow the upscli_get() call to return an error in that case:

        #include <signal​.h>
        ​.​.​.
        signal (SIGPIPE, SIG_IGN);
        ​.​.​.

upscli_list_start(3), upscli_list_next(3), upscli_strerror(3), upscli_upserror(3)

nut(7), upsclient(3), upscli_list_next(3), upscli_list_start(3), upscli_readline(3), upscli_sendline(3), upscli_splitaddr(3), upscli_splitname(3), upscli_ssl(3), upscli_strerror(3).