81 lines
3.0 KiB
Plaintext
81 lines
3.0 KiB
Plaintext
UPSCLIENT(3)
|
|
============
|
|
|
|
NAME
|
|
----
|
|
|
|
upsclient - Network UPS Tools client access library
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The Network UPS Tools (NUT) *upsclient* library provides a number of
|
|
useful functions for programs to use when communicating with
|
|
linkman:upsd[8]. Many of the low-level socket and protocol details are
|
|
handled automatically when using this interface.
|
|
|
|
State is maintained across calls in an opaque structure called `UPSCONN_t`.
|
|
Callers are expected to create one per connection. These will be
|
|
provided to most of the *upsclient* functions. The format of this
|
|
structure is subject to change, and client programs must not reference
|
|
elements within it directly.
|
|
|
|
INITIALIZATION AND CLEANUP
|
|
--------------------------
|
|
|
|
Before creating any connection, and in general using any upscli function,
|
|
you must call linkman:upscli_init[3] with proper parameters to initialize
|
|
upscli module.
|
|
|
|
To register specific host security policy, you must call
|
|
linkman:upscli_add_host_cert[3] before initialize connection to it.
|
|
|
|
In the same way, just before exiting, and after all upscli usage, you must
|
|
call linkman:upscli_cleanup[3] to flush cache files and perform other cleanup.
|
|
|
|
NETWORK FUNCTIONS
|
|
-----------------
|
|
|
|
To create a new connection, use linkman:upscli_connect[3]. This will also
|
|
initialize the `UPSCONN_t` structure. To verify that a connection has been
|
|
established later, linkman:upscli_fd[3] can be used to return the
|
|
file descriptor. Clients wishing to check for the presence and
|
|
operation of SSL on a connection may call linkman:upscli_ssl[3].
|
|
|
|
The majority of clients will use linkman:upscli_get[3] to retrieve single
|
|
items from the server. To retrieve a list, use
|
|
linkman:upscli_list_start[3] to get it started, then call
|
|
linkman:upscli_list_next[3] for each element.
|
|
|
|
Raw lines of text may be sent to linkman:upsd[8] with
|
|
linkman:upscli_sendline[3]. Reading raw lines is possible with
|
|
linkman:upscli_readline[3]. Client programs are expected to format these
|
|
lines according to the protocol, as no checking will be performed before
|
|
transmission.
|
|
|
|
At the end of a connection, you must call linkman:upsclient_disconnect[3]
|
|
to disconnect from *upsd* and release any dynamic memory associated
|
|
with the `UPSCONN_t` structure. Failure to call this function will result
|
|
in memory and file descriptor leaks in your program.
|
|
|
|
ERROR HANDLING
|
|
--------------
|
|
|
|
In the event of an error, linkman:upscli_strerror[3] will provide
|
|
human-readable details on what happened. linkman:upscli_upserror[3] may
|
|
also be used to retrieve the error number. These numbers are defined in
|
|
*upsclient.h* as 'UPSCLI_ERR_*'.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
linkman:libupsclient-config[1],
|
|
linkman:upscli_init[3], linkman:upscli_cleanup[3], linkman:upscli_add_host_cert[3],
|
|
linkman:upscli_connect[3], linkman:upscli_disconnect[3], linkman:upscli_fd[3],
|
|
linkman:upscli_getvar[3], linkman:upscli_list_next[3],
|
|
linkman:upscli_list_start[3], linkman:upscli_readline[3],
|
|
linkman:upscli_sendline[3],
|
|
linkman:upscli_splitaddr[3], linkman:upscli_splitname[3],
|
|
linkman:upscli_ssl[3], linkman:upscli_strerror[3],
|
|
linkman:upscli_upserror[3]
|