nut/docs/man/upsclient.txt

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]