idn2_to_ascii_4i(3)

📦
version 2.3.8 · 5 versions
, in alpine 3.23, alpine 3.24, arch rolling, debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, we're looking at idn2_to_ascii_4i — it's an API function from the libidn2 manual (section 3, library calls, iykyk 💅). it does the ToASCII thing. that's the whole vibe.

🌸 SYNOPSIS 🌸

#include <idn2.h>

int idn2_to_ascii_4i(const uint32_t * input, size_t inlen, char *
output, int flags);

like, yes, the line break is mid-declaration, that's just how it's printed, we respect it 🫶

🎀 ARGUMENTS 🎀

  • const uint32_t * input — the input, fr. a zero terminated Unicode (UCS-4) string. UCS-4!! that's the big one, 32 bits per character, no skimping 💖
  • size_t inlen — how many elements are in input. count them. literally count them.
  • char * output — the output zero terminated string. and babes, listen, this buffer has to have room for at least 63 characters plus the terminating zero. 63. plus the zero. do not be cute about it, allocate enough or it's giving undefined behaviour 💀
  • int flags — optional idn2_flags to modify behaviour. optional!! zero means "defaults, bestie" ✨

🦋 DESCRIPTION 🦋

so the ToASCII operation takes a sequence of Unicode code points that make up one domain label and transforms it into a sequence of code points in the ASCII range (0..7F). if ToASCII succeeds, the original sequence and the resulting sequence are equivalent labels. that's the whole point. iconic.

now the serious part, and I need you to actually read this one:

ToASCII can fail. it fails if any step of it fails. and if any step of the ToASCII operation fails on any label in a domain name, that domain name MUST NOT be used as an internationalized domain name. periodt. what you do about that failure is application-specific — that's on you and your app, not on this function.

the inputs to ToASCII are a sequence of code points. that's it. that's the input. 💅

ToASCII never alters a sequence of code points that are all in the ASCII range to begin with (although, ok, it could still fail — no promises, bestie). and applying the ToASCII operation multiple times has the same effect as applying it just once. idempotent queen 👑

the default behavior of this function (when flags are zero) is to apply the IDNA2008 rules without the TR46 amendments. but here's the tea: TR46 non-transitional processing is nowadays ubiquitous, so when you're unsure, it is recommended that you call this function with the IDN2_NONTRANSITIONAL and the IDN2_NFC_INPUT flags for compatibility with other software. do with that what you will 🌈

💀 WARNING 💀

okay so, from version 2.1.1 until before version 2.3.5, this function was deprecated in favor of idn2_to_ascii_4i2(). and even now we still encourage you to use idn2_to_ascii_4i2() when appropriate. she's the upgraded version, no cap. 🫶

⭐ RETURNS ⭐

  • on successful conversion, IDN2_OK is returned 🎉
  • if the output label would have been too long, IDN2_TOO_BIG_LABEL is returned 😭
  • or another error code is returned. there are others. it can be anything. that's the mystery of it ✨

👑 SINCE 👑

2.0.0. she's been here a minute.

🐛 REPORTING BUGS 🐛

found a bug? tell the people:

Copyright © 2002-2025 Simon Josefsson.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

(translation: use it, share it, just keep the receipt 🧾✨)

🍓 SEE ALSO 🍓

the full documentation for libidn2 is maintained as a Texinfo manual. if the info and libidn2 programs are properly installed at your site, this command:

info libidn2

should give you access to the complete manual. and as an alternative you may obtain the manual from:

https://www.gnu.org/software/libidn/libidn2/manual/

okay that's the whole page bestie, go forth and convert your labels responsibly 💖

this has been libidn2 version 2.3.8, dated idn2_to_ascii_4i(3) era — mwah, slay, bye 🎀💅

📦 where this page comes from