int upscli_get(UPSCONN_t *ups, int numq, const char **query,
int *numa, char ***answer)
.fi
.SH"DESCRIPTION"
.sp
The \fBupscli_get()\fR function takes the pointer \fIups\fR to a UPSCONN_t state structure, and the pointer \fIquery\fR to an array of \fInumq\fR query elements\&. It builds a properly\-formatted request from those elements and transmits it to \fBupsd\fR(8)\&.
.sp
Upon success, the response will be split into separate components\&. A pointer to those components will be returned in \fIanswer\fR\&. The number of usable answer components will be returned in \fInuma\fR\&.
.SH"USES"
.sp
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:
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET NUMLOGINS <ups>
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET UPSDESC <ups>
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET VAR <ups> <var>
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET TYPE <ups> <var>
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET DESC <ups> <var>
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
GET CMDDESC <ups> <cmd>
.RE
.SH"QUERY FORMATTING"
.sp
To generate a request for GET NUMLOGINS su700, you would populate query and numq as follows:
.sp
.ifn\{\
.RS4
.\}
.nf
int numq;
const char *query[2];
.fi
.ifn\{\
.RE
.\}
.sp
.ifn\{\
.RS4
.\}
.nf
query[0] = "NUMLOGINS";
query[1] = "su700";
numq = 2;
.fi
.ifn\{\
.RE
.\}
.sp
All escaping of special characters and quoting of elements with spaces is handled for you inside this function\&.
.SH"ANSWER FORMATTING"
.sp
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:
.sp
.ifn\{\
.RS4
.\}
.nf
numa = 3;
answer[0] = "NUMLOGINS"
answer[1] = "su700"
answer[2] = "1"
.fi
.ifn\{\
.RE
.\}
.sp
Notice that the value which you seek typically starts at answer[numq]\&.
.SH"ERROR CHECKING"
.sp
This function will check your query against the response from \fBupsd\fR(8)\&. For example, if you send "VAR" "su700" "ups\&.status", it will expect to see those at the beginning of the response\&.
.sp
If the results from \fBupsd\fR do not pass this case\-insensitive test against your request, this function will return an error\&. When this happens, \fBupscli_upserror\fR(3) will return \fIUPSCLI_ERR_PROTOCOL\fR\&.
.SH"ANSWER ARRAY LIFETIME"
.sp
The pointers contained within the \fIanswer\fR array are only valid until the next call to a \fIupsclient\fR function which references them\&. If you need to use data from multiple calls, you must copy it somewhere else first\&.
.sp
The \fIanswer\fR 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 \fInuma\fR elements in \fIanswer\fR\&. Such behavior is undefined, and may yield bogus data or a crash\&.
.sp
The array will be deleted after calling \fBupscli_disconnect\fR(3)\&. Any access after that point is also undefined\&.
.SH"RETURN VALUE"
.sp
The \fBupscli_get()\fR function returns 0 on success, or \-1 if an error occurs\&.
