al_cstr(3)

💅 al_cstr(3) — the Allegro 5 API girlies' guide 💅

okay so bestie, we're in the Allegro reference manual today and this one is a tiny little function with a big personality. it's al_cstr from the Allegro 5 API and honestly? she's iconic but she comes with ✨lore✨. let's get into it 🎀

---

🌸 NAME 🌸

al_cstr — Allegro 5 API, no cap 💖

🦋 SYNOPSIS 🦋

#include <allegro5/allegro.h>

const char *al_cstr(const ALLEGRO_USTR *us)

that's it. that's the whole vibe check. one function, returns a const char *, takes a pointer to a const ALLEGRO_USTR. slay 💅

✨ DESCRIPTION ✨

okay so what she does: al_cstr gets you a char * pointer to the data inside a string 🫶. literally just hands you the pointer and says "go off."

but — and this is the part where you need to listen, bestie — that pointer is only valid while the ALLEGRO_USTR(3) object is not modified and not destroyed. like, she's not gonna stick around if you start messing with her string. you change it, you free it, the pointer's gone. periodt 💀

you can pass that pointer to functions that are expecting C-style strings, but only with the following caveats. and there are three of them. and they matter. no skipping 🙈

• ALLEGRO_USTRs are allowed to contain embedded NUL ('\0') bytes. so like. that means al_ustr_size(u) and strlen(al_cstr(u)) may not agree. yeah. two different answers. she contains multitudes 😭
• An ALLEGRO_USTR may be created in such a way that it is not NUL terminated. a string which is dynamically allocated will always be NUL terminated, but a string which references the middle of another string or region of memory will not be NUL terminated. huge difference, don't sleep on it 🌈
• If the ALLEGRO_USTR references another string, the returned C string will point into the referenced string. again, no NUL terminator will be added to the referenced string. she's just pointing, not editing. main character energy but respectful 🎀

fr fr, if you're about to hand this to something that expects a nice clean C string, do a little vibe check on your NUL situation first. please. for me 💜

💖 SEE ALSO 💖

• al_ustr_to_buffer(3)
• al_cstr_dup(3)

both absolute icons, check them out 🦋

---

okay that's the whole page, go be great, and remember: the pointer is temporary, but the knowledge is forever 💅✨

Allegro reference manual — written with love, dated whenever the manual felt like it, no cap 🫶🎀