---
name: "upsclient"
section: "3"
platform: "linux"
package: "nut"
version: "2.8.5-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/upsclient"
---

# upsclient(3)

Network UPS Tools client access library

## NAME

upsclient - Network UPS Tools client access library

## DESCRIPTION

The Network UPS Tools (NUT) **upsclient** library provides a number of useful functions for client programs to use when communicating with [**upsd**(8)](/upsd/8.md). 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.

## INITIALIZATION AND CLEANUP

Before creating any connection, and in general using any upscli function, you must call [**upscli\_init**(3)](/upscli_init/3.md) with proper parameters to initialize upscli module.

To register a specific host security policy, you must call [**upscli\_add\_host\_cert**(3)](/upscli_add_host_cert/3.md) before initializing a connection to it.

In the same way, just before exiting, and after all upscli usage, you must call [**upscli\_cleanup**(3)](/upscli_cleanup/3.md) to flush cache files and perform other cleanup.

## NETWORK FUNCTIONS

To create a new connection, use [**upscli\_connect**(3)](/upscli_connect/3.md). This will also initialize the UPSCONN\_t structure. To verify that a connection has been established later, [**upscli\_fd**(3)](/upscli_fd/3.md) 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)](/upscli_ssl/3.md).

The majority of clients will use [**upscli\_get**(3)](/upscli_get/3.md) to retrieve single items from the server. To retrieve a list, use [**upscli\_list\_start**(3)](/upscli_list_start/3.md) to get it started, then call [**upscli\_list\_next**(3)](/upscli_list_next/3.md) for each element.

Raw lines of text may be sent to [**upsd**(8)](/upsd/8.md) with [**upscli\_sendline**(3)](/upscli_sendline/3.md). Reading raw lines is possible with [**upscli\_readline**(3)](/upscli_readline/3.md). 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.

## STRING FUNCTIONS

To parse the ups.status values (check whether a particular token is present) you are encouraged to use the [**upscli\_str\_contains\_token**(3)](/upscli_str_contains_token/3.md) method.

To collect unique tokens into a string in the same manner a NUT driver does, the [**upscli\_str\_add\_unique\_token**(3)](/upscli_str_add_unique_token/3.md) 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.

## ERROR HANDLING

In the event of an error, [**upscli\_strerror**(3)](/upscli_strerror/3.md) will provide human-readable details on what happened. [**upscli\_upserror**(3)](/upscli_upserror/3.md) may also be used to retrieve the error number. These numbers are defined in **upsclient.h** as *UPSCLI\_ERR\_\**.

## SEE ALSO

**nutclient**(3), **libupsclient-config**(1), [**upscli\_init**(3)](/upscli_init/3.md), [**upscli\_cleanup**(3)](/upscli_cleanup/3.md), [**upscli\_add\_host\_cert**(3)](/upscli_add_host_cert/3.md), [**upscli\_connect**(3)](/upscli_connect/3.md), [**upscli\_disconnect**(3)](/upscli_disconnect/3.md), [**upscli\_fd**(3)](/upscli_fd/3.md), **upscli\_getvar**(3), [**upscli\_list\_next**(3)](/upscli_list_next/3.md), [**upscli\_list\_start**(3)](/upscli_list_start/3.md), [**upscli\_readline**(3)](/upscli_readline/3.md), [**upscli\_sendline**(3)](/upscli_sendline/3.md), [**upscli\_splitaddr**(3)](/upscli_splitaddr/3.md), [**upscli\_splitname**(3)](/upscli_splitname/3.md), [**upscli\_ssl**(3)](/upscli_ssl/3.md), [**upscli\_strerror**(3)](/upscli_strerror/3.md), [**upscli\_upserror**(3)](/upscli_upserror/3.md), [**upscli\_str\_add\_unique\_token**(3)](/upscli_str_add_unique_token/3.md), [**upscli\_str\_contains\_token**(3)](/upscli_str_contains_token/3.md)