146 lines
3.8 KiB
Groff
146 lines
3.8 KiB
Groff
'\" t
|
|
.\" Title: upscli_list_start
|
|
.\" 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_LIST_START" "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_list_start \- begin multi\-item retrieval from a UPS
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
#include <upsclient\&.h>
|
|
.fi
|
|
.sp
|
|
.nf
|
|
int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query)
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
The \fBupscli_list_start()\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 caller must call \fBupscli_list_next\fR(3) to retrieve the elements of the list\&. Failure to retrieve the list will most likely result in the client getting out of sync with the server due to buffered data\&.
|
|
.SH "USES"
|
|
.sp
|
|
This function implements the "LIST" command in the protocol\&. As a result, you can use it to request many different things from the server\&. Some examples are:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST UPS
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST VAR <ups>
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST RW <ups>
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST CMD <ups>
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST ENUM <ups> <var>
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
LIST RANGE <ups> <var>
|
|
.RE
|
|
.SH "QUERY FORMATTING"
|
|
.sp
|
|
To see the list of variables on a UPS called \fIsu700\fR, the protocol command would be LIST VAR su700\&. To start that list with this function, you would populate query and numq as follows:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
size_t numq;
|
|
const char *query[2];
|
|
|
|
query[0] = "VAR";
|
|
query[1] = "su700";
|
|
numq = 2;
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
All escaping of special characters and quoting of elements with spaces are handled for you inside this function\&.
|
|
.SH "ERROR CHECKING"
|
|
.sp
|
|
This function checks the response from \fBupsd\fR(8) against your query\&. If it is not starting a list, or is starting the wrong type of list, it will return an error code\&.
|
|
.sp
|
|
When this happens, \fBupscli_upserror\fR(3) will return UPSCLI_ERR_PROTOCOL\&.
|
|
.SH "RETURN VALUE"
|
|
.sp
|
|
The \fBupscli_list_start()\fR function returns 0 on success, or \-1 if an error occurs\&.
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBupscli_fd\fR(3), \fBupscli_get\fR(3), \fBupscli_readline\fR(3), \fBupscli_sendline\fR(3), \fBupscli_ssl\fR(3), \fBupscli_strerror\fR(3), \fBupscli_upserror\fR(3)
|