103 lines
3 KiB
Text
103 lines
3 KiB
Text
|
UPSCLI_GET(3)
|
||
|
|
=============
|
||
|
|
|
||
|
|
NAME
|
||
|
|
----
|
||
|
|
upscli_get - retrieve data from a UPS
|
||
|
|
|
||
|
|
SYNOPSIS
|
||
|
|
--------
|
||
|
|
|
||
|
|
#include <upsclient.h>
|
||
|
|
|
||
|
|
int upscli_get(UPSCONN_t *ups, int numq, const char **query,
|
||
|
|
int *numa, char ***answer)
|
||
|
|
|
||
|
|
DESCRIPTION
|
||
|
|
-----------
|
||
|
|
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 linkman: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'.
|
||
|
|
|
||
|
|
USES
|
||
|
|
----
|
||
|
|
|
||
|
|
This function implements the "GET" command in the 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>
|
||
|
|
|
||
|
|
QUERY FORMATTING
|
||
|
|
----------------
|
||
|
|
To generate a request for `GET NUMLOGINS su700`, you would populate
|
||
|
|
query and numq as follows:
|
||
|
|
|
||
|
|
int 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.
|
||
|
|
|
||
|
|
ANSWER FORMATTING
|
||
|
|
-----------------
|
||
|
|
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:
|
||
|
|
|
||
|
|
numa = 3;
|
||
|
|
answer[0] = "NUMLOGINS"
|
||
|
|
answer[1] = "su700"
|
||
|
|
answer[2] = "1"
|
||
|
|
|
||
|
|
Notice that the value which you seek typically starts at answer[numq].
|
||
|
|
|
||
|
|
ERROR CHECKING
|
||
|
|
--------------
|
||
|
|
This function will check your query against the response from
|
||
|
|
linkman:upsd[8]. 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, linkman:upscli_upserror[3] will return 'UPSCLI_ERR_PROTOCOL'.
|
||
|
|
|
||
|
|
ANSWER ARRAY LIFETIME
|
||
|
|
---------------------
|
||
|
|
The pointers contained within the 'answer' array are only valid
|
||
|
|
until the next call to a '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 linkman:upscli_disconnect[3]. Any
|
||
|
|
access after that point is also undefined.
|
||
|
|
|
||
|
|
RETURN VALUE
|
||
|
|
------------
|
||
|
|
The *upscli_get()* function returns 0 on success, or -1 if an
|
||
|
|
error occurs.
|
||
|
|
|
||
|
|
SEE ALSO
|
||
|
|
--------
|
||
|
|
linkman:upscli_list_start[3], linkman:upscli_list_next[3],
|
||
|
|
linkman:upscli_strerror[3], linkman:upscli_upserror[3]
|