195 lines
5.3 KiB
Groff
195 lines
5.3 KiB
Groff
'\" 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)
|