1
.TH UPSCLIENT 3 "Tue May 13 2003" "" "Network UPS Tools (NUT)"
3
upsclient - Network UPS Tools client access library
6
The Network UPS Tools (NUT) \fBupsclient\fP library provides a number of
7
useful functions for programs to use when communicating with
8
\fBupsd\fP(8). Many of the low-level socket and protocol details are
9
handled automatically when using this interface.
11
State is maintained across calls in an opaque structure called UPSCONN.
12
Callers are expected to create one per connection. These will be
13
provided to most of the \fBupsclient\fP functions. The format of this
14
structure is subject to change, and client programs must not reference
15
elements within it directly.
18
To create a new connection, use \fBupscli_connect\fP(3). This will also
19
initialize the UPSCONN structure. To verify that a connection has been
20
established later, \fBupscli_fd\fP(3) can be used to return the
21
file descriptor. Clients wishing to check for the presence and
22
operation of SSL on a connection may call \fBupscli_ssl\fR(3).
24
The majority of clients will use \fBupscli_get\fP(3) to retrieve single
25
items from the server. To retrieve a list, use
26
\fBupscli_list_start\fP(3) to get it started, then call
27
\fBupscli_list_next\fP(3) for each element.
29
Raw lines of text may be sent to \fBupsd\fP with
30
\fBupscli_sendline\fP(3). Reading raw lines is possible with
31
\fBupscli_readline\fP(3). Client programs are expected to format these
32
lines according to the protocol, as no checking will be performed before
35
At the end of a connection, you must call \fBupsclient_disconnect\fR(3)
36
to disconnect from \fBupsd\fP and release any dynamic memory associated
37
with the UPSCONN structure. Failure to call this function will result
38
in memory and file descriptor leaks in your program.
41
In the event of an error, \fBupscli_strerror\fR(3) will provide
42
human-readable details on what happened. \fBupscli_upserror\fR(3) may
43
also be used to retrieve the error number. These numbers are defined in
44
\fBupsclient.h\fP as \fIUPSCLI_ERR_*\fP.
46
.SH COMPATIBILITY FUNCTIONS
47
The functions \fBupscli_getvar\fP(3) and \fBupscli_getlist\fP(3) are
48
provided for compatibility with older versions of \fBupsd\fP. They only
49
work with the old variable names like STATUS and UTILITY. Conversely,
50
the other functions only work with the new variable names like
51
ups.status and input.voltage.
53
.BR upscli_connect "(3), " upscli_disconnect "(3), " upscli_fd "(3), "
54
.BR upscli_get "(3), " upscli_getlist "(3), "
55
.BR upscli_getvar "(3), " upscli_list_next "(3), "
56
.BR upscli_list_start "(3), " upscli_readline "(3), "
57
.BR upscli_sendline "(3), " upscli_splitname "(3), "
58
.BR upscli_ssl "(3), " upscli_strerror "(3), "
59
.BR upscli_upserror "(3) "
added
removed
man/upsclient.3
