TEXTDOMAIN(3)

📦
version 1.0 · 6 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 TEXTDOMAIN 💖

okay bestie so this is textdomain, a lil function from the Library Functions Manual and it's literally the thing that tells your program which translation files to go look in. so unserious of it to be this important tbh 🫶

✨ NAME ✨

textdomain — sets the domain for all your future gettext() calls 🎀

🌸 SYNOPSIS 🌸

#include <libintl.h>

char * textdomain (const char * domainname);

like that's it. one include, one function, one little char * and you're in your i18n era ✨

💅 DESCRIPTION 💅

okay so textdomain either sets or gets the current message domain. it's giving switch-hitter, honestly. 👑

and what even is a message domain?? so glad you asked. a message domain is a set of translatable msgid messages. usually every software package has its own message domain — your app gets one, my app gets one, everyone's got their own little folder of translations. no sharing, no drama. the domain name is what gets used to figure out which message catalog a translation is looked up in, and heads up bestie: it must be a non-empty string. empty string? not the vibe. 🙅

now here's where it gets cute. the current message domain is the one that gets used by:

  • the gettext and ngettext functions
  • the dgettext, dcgettext, dngettext and dcngettext functions — but only when they're called with a NULL domainname argument 🫶

so like, if you pass NULL, they're like "okay cool I'll just use whatever the current domain is." teamwork. iconic.

if domainname is not NULL: the current message domain gets set to domainname. and the way the function stores it internally? it keeps a copy of the domainname argument. so you can free your own string, she's got her own. self-sufficient queen 💅

if domainname is NULL: the function just returns the current message domain. no setting, just vibes and information. 💖

🌈 RETURN VALUE 🌈

if it works, textdomain returns the current message domain — after possibly having changed it. so you get the fresh new one, slay. 🎀

okay but listen: the resulting string is valid until the next textdomain call and it must not be modified or freed. do NOT touch it. do NOT free it. it is not yours. it is hers. hands off bestie 😭

and if a memory allocation failure happens? she sets errno to ENOMEM and returns NULL. tragic. anyway. 💀

🦋 ERRORS 🦋

here's the error that can happen (among others, so like, stay alert):

  • ENOMEM — not enough memory available. the computer is broke, the memory is gone, it's over. 😭

💀 BUGS 💀

okay so this one's a lil legacy situation. the return type ought to be const char *... but it's char *. why? to avoid warnings in C code predating ANSI C. so basically it's a historical artifact holding the whole thing hostage. we love a vintage design decision that we simply cannot change now. 🙈

👑 SEE ALSO 👑

and that's the whole page, bestie!! this one's from GNU gettext 1.0, dated May 2001 — so like, older than most of us, but still out here doing her lil domain-setting job. periodt. 💖✨🦋

📦 where this page comes from