idn2_lookup_ul(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 💖

idn2_lookup_ul — bestie, this is an API function and it's literally the one that turns your cute local-language domain into something the DNS can actually look up 🦋

✨ SYNOPSIS ✨

#include <idn2.h>

int idn2_lookup_ul(const char * src, char ** lookupname, int flags);

🎀 ARGUMENTS 🎀

  • const char * src — your input, okay? And it's a zero-terminated string that's encoded in whatever the locale says is the default coding system. So like, not necessarily UTF-8 yet. We got you though.
  • char ** lookupname — this is the output, and it's a newly allocated variable (so yes, you own that memory, don't ghost it) holding the name you're gonna look up in DNS.
  • int flags — optional idn2_flags that change how the function behaves. Totally optional, but the options are cute so keep reading 💅

🌸 DESCRIPTION 🌸

okay so. This function does the IDNA2008 lookup string conversion on the domain name src, exactly like it says in section 5 of RFC 5891. And here's the tea: the input is assumed to be encoded in the locale's default coding system, and this function will transcode it to UTF-8 and NFC normalize it for you. No cap. It handles the glow-up all on its own ✨

Wanna convert any input A-labels to U-labels and do some extra testing on top? Pass IDN2_ALABEL_ROUNDTRIP in flags. And bestie, this has been the default since version 2.2. If you wanna switch that behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP.

Pass IDN2_TRANSITIONAL to enable Unicode TR46 transitional processing, and IDN2_NONTRANSITIONAL to enable Unicode TR46 non-transitional processing. Two vibes, pick your fighter 🫶

Multiple flags? Yes you can, just binary-or them together, like:

IDN2_ALABEL_ROUNDTRIP | IDN2_NONTRANSITIONAL

Also IDN2_NFC_INPUT in flags is always enabled in this function. Like, it's not optional, it's just the rules. Periodt.

And post-version 0.11: lookupname may be NULL, which lets you test the lookup of src without allocating any memory. Very demure, very mindful 🧚

👑 RETURNS 👑

On a successful conversion you get IDN2_OK back, slay 💅 But if the conversion from locale to UTF-8 fails, then IDN2_ICONV_FAIL is returned. And if the output domain or any label would have been too long, you get IDN2_TOO_BIG_DOMAIN or IDN2_TOO_BIG_LABEL. Or, you know, another error code is returned. It's giving "read the return value, bestie" 😭

⭐ SINCE ⭐

0.1 — an absolute icon, been here since the beginning 👑

🐛 REPORTING BUGS 🐛

Found a bug? Report it to <help-libidn@gnu.org>. They wanna hear from you fr fr.

General guidelines for reporting bugs live at: https://www.gnu.org/gethelp/

Libidn2 home page: https://www.gnu.org/software/libidn2/

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. (yes, it's that free, we love to see it 🌈)

🌟 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, then this command:

info libidn2

should give you access to the complete manual. Obsessed with that for you honestly.

As an alternative you may obtain the manual from:

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

okay that's the whole page bestie!! this was libidn2 version 2.3.8, from the idn2_lookup_ul(3) manual, and yes I read every single line so you don't have to 🎀 go convert some domain names, you're gonna do amazing, mwah 💖🦋🌸

📦 where this page comes from