LIBNUTCLIENT_TCP(3)

💅 LIBNUTCLIENT_TCP(3) — the TCP era of libnutclient, bestie edition ✨

okay so real talk, this is a page straight out of the NUT Manual (Network UPS Tools, if you're new here 🫶) and it's all about the TCP-flavored functions in the high-level client access library. it's giving "let me talk to my UPS over the network" main character energy. no cap. 🔥

---

✨ SYNOPSIS ✨

like, literally just include the thing:

#include <nutclient.h>
#include <cstdint> /* uint16_t */
#include <ctime> /* time_t */

typedef NUTCLIENT_t NUTCLIENT_TCP_t;

NUTCLIENT_TCP_t nutclient_tcp_create_client(
        const char* host, uint16_t port);

int nutclient_tcp_is_connected(NUTCLIENT_TCP_t client);

void nutclient_tcp_disconnect(NUTCLIENT_TCP_t client);

int nutclient_tcp_reconnect(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_timeout(NUTCLIENT_TCP_t client, time_t timeout);

time_t nutclient_tcp_get_timeout(NUTCLIENT_TCP_t client);

/* SSL (NUT STARTTLS) support, behavior may be build-dependent
 * (none/OpenSSL/NSS): */

/* Capabilities of this build, bitmask: */
#define UPSCLI_SSL_CAPS_NONE    0       /* No ability to use SSL */
#define UPSCLI_SSL_CAPS_OPENSSL 1       /* Can use OpenSSL-specific setup */
#define UPSCLI_SSL_CAPS_NSS     2       /* Can use Mozilla NSS-specific setup */
int nutclient_tcp_get_ssl_caps(void);

/* Is the specified client currently connected in SSL mode? */
int nutclient_tcp_is_ssl(NUTCLIENT_TCP_t client);

NUTCLIENT_TCP_t nutclient_tcp_create_client_ssl_OpenSSL(
        const char* host, uint16_t port, int try_ssl,
        int force_ssl, int certverify,
        const char *ca_path, const char *ca_file,
        const char *cert_file, const char *key_file, const char *key_pass);

void nutclient_tcp_set_ssl_config_OpenSSL(NUTCLIENT_TCP_t client,
        int force_ssl, int certverify,
        const char *ca_path, const char *ca_file,
        const char *cert_file, const char *key_file, const char *key_pass);

NUTCLIENT_TCP_t nutclient_tcp_create_client_ssl_NSS(
        const char* host, uint16_t port, int try_ssl,
        int force_ssl, int certverify,
        const char *certstore_path, const char *certstore_pass,
        const char *certstore_prefix,
        const char *certhost_name,
        const char *certident_name);

void nutclient_tcp_set_ssl_config_NSS(NUTCLIENT_TCP_t client,
        int force_ssl, int certverify,
        const char *certstore_path, const char *certstore_pass,
        const char *certstore_prefix,
        const char *certhost_name,
        const char *certident_name);

/* Individual SSL option getters/setters: */

void nutclient_tcp_set_ssl_try(NUTCLIENT_TCP_t client, int try_ssl);
int nutclient_tcp_get_ssl_try(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_force(NUTCLIENT_TCP_t client, int force_ssl);
int nutclient_tcp_get_ssl_force(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_certverify(NUTCLIENT_TCP_t client, int certverify);
int nutclient_tcp_get_ssl_certverify(NUTCLIENT_TCP_t client);

/* OpenSSL (PEM): Trusted CA directory: */
void nutclient_tcp_set_ssl_capath(NUTCLIENT_TCP_t client, const char* ca_path);
const char* nutclient_tcp_get_ssl_capath(NUTCLIENT_TCP_t client);

/* Trusted CA file: */
void nutclient_tcp_set_ssl_cafile(NUTCLIENT_TCP_t client, const char* ca_file);
const char* nutclient_tcp_get_ssl_cafile(NUTCLIENT_TCP_t client);

/* Client certificate (public): */
void nutclient_tcp_set_ssl_certfile(NUTCLIENT_TCP_t client, const char* cert_file);
const char* nutclient_tcp_get_ssl_certfile(NUTCLIENT_TCP_t client);

/* Client key (private): */
void nutclient_tcp_set_ssl_keyfile(NUTCLIENT_TCP_t client, const char* key_file);
const char* nutclient_tcp_get_ssl_keyfile(NUTCLIENT_TCP_t client);

/* OpenSSL and NSS: Client key (private): */
void nutclient_tcp_set_ssl_keypass(NUTCLIENT_TCP_t client, const char* key_pass);
const char* nutclient_tcp_get_ssl_keypass(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_certstore_path(NUTCLIENT_TCP_t client,
        const char* certstore_path);
const char* nutclient_tcp_get_ssl_certstore_path(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_certstore_prefix(NUTCLIENT_TCP_t client,
        const char* certstore_prefix);
const char* nutclient_tcp_get_ssl_certstore_prefix(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_certident_name(NUTCLIENT_TCP_t client,
        const char* certident_name);
const char* nutclient_tcp_get_ssl_certident_name(NUTCLIENT_TCP_t client);

void nutclient_tcp_set_ssl_certhost_name(NUTCLIENT_TCP_t client,
        const char* certhost_name);
const char* nutclient_tcp_get_ssl_certhost_name(NUTCLIENT_TCP_t client);

---

🌸 DESCRIPTION 🌸

so these functions? they let you manage connections to upsd(8) using the NUT TCP protocol. iconic behavior honestly. 💖

• nutclient_tcp_create_client() — this one creates the NUTCLIENT_TCP_t context and intends to connect to upsd at host and port. (yes "intends", we said what we said ✨)

🚨 bestie listen: the context must be freed by nutclient_destroy(). don't be out here leaking, that's not the vibe. 😭

• host can be a server name or a valid IPv4 or IPv6 address like "localhost", "127.0.0.1" or "::1". slay, all the address families get an invite. 🦋
• port is a valid TCP port, generally 3493. that's the one, that's the classic. 👑

• nutclient_tcp_is_connected() — vibe check 💅 — it tests if the connection is valid.
• nutclient_tcp_disconnect() — forces the specified connection to disconnect. it's over, no more texts. 💀
• nutclient_tcp_reconnect() — forces a connection to reconnect, disconnecting it first if needed. we love a fresh start. 🔥
• nutclient_tcp_set_timeout() — sets the timeout duration for I/O operations. ⏰
• nutclient_tcp_get_timeout() — retrieves the timeout duration for I/O operations. the receipts, basically. 🧾

timeout values are specified in seconds, and use negative values for blocking. yes, negative = "i'll wait, i have nowhere to be" energy. 🫶

---

🔍 SEE ALSO 🔍

libnutclient(3) · libnutclient_general(3) — go read your sisters bestie, iykyk 🌈

---

okay that's the whole page 🎀 it's Network UPS Tools 2.8.5, dated 06/21/2026, and this was LIBNUTCLIENT_TCP(3) from the NUT Manual. mwah, go free your contexts and stay encrypted 💜✨