66 lines
2 KiB
Groff
66 lines
2 KiB
Groff
|
.TH UPSCLI_LIST_START 3 "Mon Jan 22 2007" "" "Network UPS Tools (NUT)"
|
||
|
|
.SH NAME
|
||
|
|
upscli_list_start \- begin multi\(hyitem retrieval from a UPS
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
.B #include <upsclient.h>
|
||
|
|
.sp
|
||
|
|
.BI "int upscli_list_start(UPSCONN *ups, int numq, const char **query)"
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
The \fBupscli_list_start()\fP function takes the pointer \fIups\fP to a
|
||
|
|
UPSCONN state structure, and the pointer \fIquery\fP to an array of
|
||
|
|
\fInumq\fP query elements. It builds a properly\(hyformatted request from
|
||
|
|
those elements and transmits it to \fBupsd\fP(8).
|
||
|
|
.PP
|
||
|
|
Upon success, the caller must call \fBupscli_list_next\fP(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.
|
||
|
|
.PP
|
||
|
|
.SH "USES"
|
||
|
|
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:
|
||
|
|
.PP
|
||
|
|
\(hy LIST UPS
|
||
|
|
\(hy LIST VAR <ups>
|
||
|
|
\(hy LIST RW <ups>
|
||
|
|
\(hy LIST CMD <ups>
|
||
|
|
\(hy LIST ENUM <ups> <var>
|
||
|
|
|
||
|
|
.SH QUERY FORMATTING
|
||
|
|
To see the list of variables on a UPS called su700, the protocol command
|
||
|
|
would be "LIST VAR su700". To start that list with this function, you
|
||
|
|
would populate query and numq as follows:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
int numq;
|
||
|
|
const char *query[2];
|
||
|
|
|
||
|
|
query[0] = "VAR";
|
||
|
|
query[1] = "su700";
|
||
|
|
numq = 2;
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
All escaping of special characters and quoting of elements with spaces
|
||
|
|
is handled for you inside this function.
|
||
|
|
.PP
|
||
|
|
.SH "ERROR CHECKING"
|
||
|
|
This function checks the response from \fBupsd\fP against your query.
|
||
|
|
If it is not starting a list, or is starting the wrong type of list, it
|
||
|
|
will return an error code.
|
||
|
|
.PP
|
||
|
|
When this happens, \fBupscli_upserror\fP(3) will return
|
||
|
|
\fIUPSCLI_ERR_PROTOCOL\fP.
|
||
|
|
.PP
|
||
|
|
.SH "RETURN VALUE"
|
||
|
|
The \fBupscli_list_start()\fP function returns 0 on success, or \-1 if an
|
||
|
|
error occurs.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR upscli_fd "(3), "upscli_get "(3), "
|
||
|
|
.BR upscli_readline "(3), "upscli_sendline "(3), "
|
||
|
|
.BR upscli_ssl "(3), "
|
||
|
|
.BR upscli_strerror "(3), "upscli_upserror "(3) "
|
||
|
|
|