UPSCLI_STR_ADD_UNIQU(3)

🦋 UPSCLI_STR_ADD_UNIQU(3) — the one where we add tokens but only the unique ones 💅

okay bestie so this is a page from the NUT Manual (that's Network UPS Tools, iconic name, iykyk) and it's all about upscli_str_add_unique_token — yes that's the whole function name, she's long, she's giving main character energy, we support her 🎀

---

✨ NAME ✨

upscli_str_add_unique_token — add a unique token into a string buffer, with optional callbacks as needed by implementation 🫶

---

🌸 SYNOPSIS 🌸

        #include <upsclient.h>

        int     upscli_str_add_unique_token(char *tgt, size_t tgtsize, const char *token,
                                int (*callback_always)(char *, size_t, const char *),
                                int (*callback_unique)(char *, size_t, const char *) );

like, that's the signature, copy it exactly, don't come for me 🫡

---

💖 DESCRIPTION 💖

so the upscli_str_add_unique_token() function takes the pointer tgt to a caller-provided char * buffer of size tgtsize, and the pointer token to a contiguous token that should be added to the end of the tgt buffer — if it's not there yet. no duplicates allowed, it's giving exclusive VIP list 💅

The token contents are stripped of surrounding space characters, and the method recurses to independently process each space-separated token inside (if there are any spaces left). so yes, she's a little recursive gremlin, we love that for her 🧚

The resulting tgt buffer would eventually collect a string comprised of unique token values in order of first mention, separated by single space characters (ASCII 0x20). first come, first served, one space between, no drama ✨

Optionally calls callback_always (if not NULL) after checking the input for spaces (and maybe recursing) and before checking if the token is already there, and/or callback_unique (if not NULL) after checking for uniqueness and just before going to add a newly seen token. so those callbacks are basically little bodyguards standing at different points in the queue 😭

• If such callback returns 0, abort the addition of token and return -3. periodt, no token for you 🚫

It is up to the caller to dynamically or statically allocate the tgt buffer and free() it if needed. As far as this method is concerned, the buffer may be recycled (in data processing loops) by setting the initial character to '\0', making it an empty string again. cute lil reset, obsessed 🌈

---

🔥 RETURN VALUE 🔥

The upscli_str_add_unique_token() function returns a numeric code, and each one means something, so pay attention bestie 👑

• 0 if the token value was already there in tgt buffer — she was already at the party, nothing to do 💀
• 1 if token was added successfully — slay, new guest unlocked 🎉
• -1 if we needed to add the token, but it did not fit under the tgtsize limit — the buffer said no room, tragic 😭
• -2 if either token or tgt string was NULL, or if token was empty — literally nothing to work with, bestie 🙈
• -3 if the token was rejected by the optional callback method returning 0 — bodyguard said nope 🛑

---

🌟 SEE ALSO 🌟

• upscli_str_contains_token(3) — her cousin, the one who just checks if something's there instead of adding it 🦋

---

okay that's the whole page, go forth and add your unique tokens responsibly, bestie 💜

Network UPS Tools 2.8.5 — date 06/21/2026 — mwah, that's the version and date, copy 'em if you need 'em, she's signed off and glowing ✨👑💅