ustrzncpy(3alleg4)

📦 version 4.4.3.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 ustrzncpy — bestie, this is the size-aware string copier 💖

okay so you're in the 3alleg4 section of the manual, which means we're talking Allegro game programming library, and we're talking about a lil function called ustrzncpy. she copies a string into another one, but with size specified. she's careful. she's considerate. she has boundaries (literally, the size parameter is her boundaries). 🎀

✨ SYNOPSIS ✨

#include <allegro.h>

char *ustrzncpy(char *dest, int size, const char *src, int n);

that's it, that's the whole vibe. three things in, one string out. 💅

🌸 DESCRIPTION 🌸

so, ustrzncpy() is basically ustrzncpy()'s older sister ustr zcpy... no wait, she's literally ustr zcpy's sister: this function is like ustr zcpy() except for one thing — she will copy no more than n characters from src into dest. 👑

and dest? her length in bytes is specified by size, and she is guaranteed to be null-terminated even if src is bigger than size. yes bestie, even then. she always closes with a null. she always says goodbye properly. ✨

and if src is shorter than n characters? no problem, we just pad. null characters get appended to dest until n characters have been written. it's giving "filling the rest of the row with cushions so nothing wobbles." 🫶

in any case, dest is guaranteed to be null-terminated. always. every time. no cap.

⚠️ okay this part is important and lowkey a jump scare: even for empty strings, your destination string must have at least enough bytes to store the terminating null character of the string, and your parameter size must reflect this. otherwise — and I'm not being dramatic, this is just what happens — the debug version of Allegro will abort at an assertion, and the release version of Allegro will overrun the destination buffer. 💀

so like. count your bytes. size matters (in the buffer sense). don't skip the null. 🙈

🌈 RETURN VALUE 🌈

the return value is the value of dest. that's it. she gives you back your own pointer like a lil boomerang. 🪃 iconic behavior.

👑 SEE ALSO 👑

go read those too bestie, they're all in the friend group. 💜

alright that's the whole page!! this was Allegro, version 4.4.3, and the manual page is ustrzncpy(3alleg4) — mwah, go write some safe strings, i'm obsessed with you 🦋✨💖

📦 where this page comes from