LIBNUTCLIENT_TCP(3)

💖 NAME 💖

okay so bestie, this page is libnutclient_tcp(3) — it's part of the NUT Manual and it's literally all about the TCP protocol functions for the Network UPS Tools high-level client access library. 🌸

The whole girlie squad of functions living here:

• libnutclient_tcp
• nutclient_tcp_create_client
• nutclient_tcp_is_connected
• nutclient_tcp_disconnect
• nutclient_tcp_reconnect
• nutclient_tcp_set_timeout
• nutclient_tcp_get_timeout
• nutclient_tcp_get_ssl_caps
• nutclient_tcp_is_ssl

---

✨ SYNOPSIS ✨

the way that you just #include and go 💅

#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 like. all of these functions are here so you can manage connections to upsd(8) using the NUT TCP protocol. no cap. 🔥

• nutclient_tcp_create_client() — this one creates the NUTCLIENT_TCP_t context and intends to connect to upsd at host and port. it's giving main character energy fr fr.

the context must be freed by nutclient_destroy(). don't forget bestie, she's not gonna clean up after herself 😭

• host can be a server name or a valid IPv4 or IPv6 address, like "localhost", "127.0.0.1" or "::1". ✨
• port is a valid TCP port, generally 3493. 💅

• nutclient_tcp_is_connected() — vibe checks whether the connection is valid. 🫶
• nutclient_tcp_disconnect() — forces the specified connection to disconnect. bye bye 👋
• nutclient_tcp_reconnect() — forces a connection to reconnect, disconnecting it first if that's needed. iconic comeback behavior 💖
• nutclient_tcp_set_timeout() — sets the timeout duration for I/O operations. ⏳
• nutclient_tcp_get_timeout() — retrieves the timeout duration for I/O operations. 👑

timeout values are specified in seconds, and you use negative values for blocking. (yes, negative = blocking, that's the rule, no notes 💀)

---

🌈 SEE ALSO 🌈

• libnutclient(3)
• libnutclient_general(3)

---

and that's the whole page bestie!! 🎀 this was brought to you by Network UPS Tools 2.8.5, dated 10/07/2026 — go forth and connect responsibly, mwah 💜🦋✨