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:
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\&.
If \fBupsd\fR 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 \fBupscli_get()\fR call to return an error in that case:
