nut/docs/man/upscli_get.3

'\" t
.\"     Title: upscli_get
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/26/2022
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "UPSCLI_GET" "3" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
upscli_get \- retrieve data from an UPS
.SH "SYNOPSIS"
.sp
.nf
#include <upsclient\&.h>
.fi
.sp
.nf
int upscli_get(UPSCONN_t *ups, size_t numq, const char **query,
                       size_t *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\&.
.sp
Some examples are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GET NUMLOGINS <ups>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GET UPSDESC <ups>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GET VAR <ups> <var>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GET TYPE <ups> <var>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GET DESC <ups> <var>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.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
.if n \{\
.RS 4
.\}
.nf
        size_t numq;
        const char *query[2];

        query[0] = "NUMLOGINS";
        query[1] = "su700";
        numq = 2;
.fi
.if n \{\
.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\&.
.sp
Since this is split up for you, the values work out like this:
.sp
.if n \{\
.RS 4
.\}
.nf
        size_t numa;

        numa = 3;
        answer[0] = "NUMLOGINS"
        answer[1] = "su700"
        answer[2] = "1"
.fi
.if n \{\
.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\&.
.sp
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\&.
.sp
The following code in your initialization function will allow the \fBupscli_get()\fR call to return an error in that case:
.sp
.if n \{\
.RS 4
.\}
.nf
#include <signal\&.h>
\&.\&.\&.
signal (SIGPIPE, SIG_IGN);
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBupscli_list_start\fR(3), \fBupscli_list_next\fR(3), \fBupscli_strerror\fR(3), \fBupscli_upserror\fR(3)