132 lines
3.4 KiB
Plaintext
132 lines
3.4 KiB
Plaintext
UPSCLI_GET(3)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
|
|
upscli_get - retrieve data from an UPS
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
#include <upsclient.h>
|
|
|
|
int upscli_get(UPSCONN_t *ups, size_t numq, const char **query,
|
|
size_t *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:
|
|
|
|
------
|
|
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.
|
|
|
|
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:
|
|
|
|
------
|
|
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]`.
|
|
|
|
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.
|
|
|
|
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);
|
|
...
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
linkman:upscli_list_start[3], linkman:upscli_list_next[3],
|
|
linkman:upscli_strerror[3], linkman:upscli_upserror[3]
|