nut/docs/man/upscli_get.txt

UPSCLI_GET(3)
=============

NAME
----
upscli_get - retrieve data from a UPS

SYNOPSIS
--------

 #include <upsclient.h>

 int upscli_get(UPSCONN_t *ups, unsigned int numq, const char **query,
			unsigned 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:

	unsigned 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:

	unsigned int 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]