upsclient - Man Page

The Network UPS Tools (NUT) upsclient library provides a number of useful functions for client programs to use when communicating with upsd(8)​. Many of the low-level socket and protocol details are handled automatically when using this interface, also known as "upscli" API​.

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​.

Before creating any connection, and in general using any upscli function, you must call upscli_init(3) with proper parameters to initialize upscli module​.

To register a specific host security policy, you must call upscli_add_host_cert(3) before initializing a connection to it​.

In the same way, just before exiting, and after all upscli usage, you must call upscli_cleanup(3) to flush cache files and perform other cleanup​.

To create a new connection, use upscli_connect(3)​. This will also initialize the UPSCONN_t structure​. To verify that a connection has been established later, 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 upscli_ssl(3)​.

The majority of clients will use upscli_get(3) to retrieve single items from the server​. To retrieve a list, use upscli_list_start(3) to get it started, then call upscli_list_next(3) for each element​.

Raw lines of text may be sent to upsd(8) with upscli_sendline(3)​. Reading raw lines is possible with 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 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​.

To parse the ups​.status values (check whether a particular token is present) you are encouraged to use the upscli_str_contains_token(3) method​.

To collect unique tokens into a string in the same manner a NUT driver does, the upscli_str_add_unique_token(3) can be helpful​.

You are welcome to consult the NUT source code base for use of equivalent methods to implement such features as status_init(), status_get(), status_set() and status_commit() methods in its data-processing loops​.

In the event of an error, upscli_strerror(3) will provide human-readable details on what happened​. upscli_upserror(3) may also be used to retrieve the error number​. These numbers are defined in upsclient​.h as UPSCLI_ERR_*​.

nutclient(3), libupsclient-config(1), upscli_init(3), upscli_cleanup(3), upscli_add_host_cert(3), upscli_connect(3), upscli_disconnect(3), upscli_fd(3), upscli_getvar(3), upscli_list_next(3), upscli_list_start(3), upscli_readline(3), upscli_sendline(3), upscli_splitaddr(3), upscli_splitname(3), upscli_ssl(3), upscli_strerror(3), upscli_upserror(3), upscli_str_add_unique_token(3), upscli_str_contains_token(3)

libnutclient(3), nut(7), upscli_report_build_details(3), upscli_ssl(3), upscli_ssl_caps(3), upslog(8).