UPSCLIENT(3)

📦
version 2.8.5 · 17 versions
, in fedora 43, fedora 44

✨ UPSCLIENT ✨

okay bestie, welcome to the NUT Manual 💖 this one's the upsclient page, and it's literally the front door to the whole client-side library. let's get into it 🫶

🌸 NAME 🌸

upsclient — Network UPS Tools client access library

🦋 DESCRIPTION 🦋

The Network UPS Tools (NUT) upsclient library is serving up a whole bunch of useful functions for client programs to use when they're talking to upsd(8). So many of the low-level socket and protocol details get handled automatically when you use this interface — which, iykyk, also goes by the name "upscli" API. no cap, it does the boring parts for you 💅

State is maintained across calls in an opaque structure called UPSCONN_t. Callers are expected to create one of these per connection. most of the upsclient functions are gonna want one of these handed to them. and listen: the format of this structure is subject to change, so client programs must not reference elements within it directly. hands off, bestie 🙈

🎀 INITIALIZATION AND CLEANUP 🎀

Before you create any connection — honestly, before you do basically anything with a upscli function — you must call upscli_init(3) with proper parameters to initialize the upscli module. it's the vibe check you do first, periodt.

To register a specific host security policy, you must call upscli_add_host_cert(3) before initializing a connection to that host. order matters, bestie 🔥

And in the same way, right before you exit, and after all upscli usage is done, you must call upscli_cleanup(3) to flush cache files and do all the other cleanup stuff. it's giving "tidy up before you leave the party" 🌈

💜 NETWORK FUNCTIONS 💜

To create a new connection, use upscli_connect(3). this one also initializes the UPSCONN_t structure for you. iconic 🎀 To verify later that a connection actually got established, upscli_fd(3) can be used to return the file descriptor. And for the clients out there wanting to check whether SSL is present and operating on a connection, you can call upscli_ssl(3). slay.

The majority of clients are gonna use upscli_get(3) to retrieve single items from the server. To retrieve a list instead, use upscli_list_start(3) to get it started, then call upscli_list_next(3) for each element. one at a time, no rushing ✨

Raw lines of text may be sent to upsd(8) with upscli_sendline(3). And reading raw lines is possible with upscli_readline(3). but here's the thing — client programs are expected to format these lines according to the protocol, because no checking will be performed before transmission. you're on your own with the formatting, bestie, the library is not gonna catch you 😭

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.

🚨 lowkey important: failure to call this function will result in memory and file descriptor leaks in your program. that's not a vibe. that's the opposite of a vibe. call it. 💀

🍓 STRING FUNCTIONS 🍓

To parse the ups.status values — like checking whether a particular token is present — you are encouraged to use the upscli_str_contains_token(3) method. it's the moment 🧚

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

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. go read the source, it's giving study date 📚

⭐ ERROR HANDLING ⭐

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_*. so when something goes wrong, you actually get to know what went wrong. love that for you 💖

👑 SEE ALSO 👑

and that's the whole page, bestie!! 🦋 this one's from Network UPS Tools 2.8.5, dated 10/07/2026 — so yeah, tell everyone you got your NUT facts from the freshest source 💅✨ go forth and write clients, ily, mwah 🫶💖

📦 where this page comes from