ICONV(1)

📦 version 1.19, in arch rolling

💫 ICONV(1) — character set conversion, but make it a glow-up 💫

(page one of the General Commands Manual, and yes bestie, we're in the big leagues now)

🌸 SYNOPSIS 🌸

iconv [OPTION...] [-f encoding] [-t encoding] [inputfile ...]
iconv -l

✨ DESCRIPTION ✨

Okay so picture this: iconv converts text from one encoding to another encoding. Literally its whole job. 🎀

More precisely (because precision is the moment), it converts from the encoding you gave to -f to the encoding you gave to -t. Either one of those defaults to the encoding of your current locale if you don't say anything — so if you're being lazy, it's got you. All the inputfiles get read and converted in turn, one after another; and if no inputfile is given at all? Standard input, babe. The converted text is printed to standard output.

The encodings permitted are system dependent — no cap. For the libiconv implementation, they're listed over in the iconv_open(3) manual page. 👑

💅 OPTIONS 💅

🦋 Options controlling the input and output format

  • -f encoding, --from-code=encoding — specifies the encoding of the input. Like, where the text is coming from.
  • -t encoding, --to-code=encoding — specifies the encoding of the output. Where it's going. Glow-up destination.

🔥 Options controlling conversion problems

  • -c — when you hand it this option, characters that cannot be converted are silently discarded instead of leading to a conversion error. Poof. Gone. Not a word. 😭
  • --unicode-subst=formatstring — when given, Unicode characters that cannot be represented in the target encoding get replaced with a placeholder string constructed from the given formatstring, applied to the Unicode code point. The formatstring must be a format string in the same format as for the printf command or the printf() function, taking either no argument or exactly one unsigned integer argument. That's the whole rule, periodt.
  • --byte-subst=formatstring — when given, bytes in the input that are not valid in the source encoding get replaced with a placeholder string constructed from the given formatstring, applied to the byte's value. Same deal: the formatstring must be a format string in the same format as for the printf command or the printf() function, taking either no argument or exactly one unsigned integer argument.
  • --widechar-subst=formatstring — when given, wide characters in the input that are not valid in the source encoding get replaced with a placeholder string constructed from the given formatstring, applied to the byte's value. Yep, same formatstring rules as the other two: same format as for the printf command or the printf() function, taking either no argument or exactly one unsigned integer argument.

🎀 Options controlling error output

  • -s, --silent — when given, error messages about invalid or unconvertible characters are omitted, but the actual converted text is unaffected. So like, the drama is quieted, the output is untouched. 💯
🫶 Heads up: the iconv -l or iconv --list command lists the names of the supported encodings, in a system dependent format. For the libiconv implementation, the names are printed in upper case, separated by whitespace, and alias names of an encoding are listed on the same line as the encoding itself.

🌈 ENVIRONMENT 🌈

Conversion from/to EBCDIC encodings can be modified in a very specific way: if the environment variable ICONV_EBCDIC_ZOS_UNIX is set to a non-empty value, the EBCDIC newline 0x15 will get mapped to LF instead of NEL. That's it, that's the whole vibe. 🧚

⭐ EXAMPLES ⭐

iconv -f ISO-8859-1 -t UTF-8

converts input from the old West-European encoding ISO-8859-1 to Unicode. Classic. Iconic. Nate your fave.

iconv -f KOI8-R --byte-subst="<0x%x>"
                --unicode-subst="<U+%04X>"

converts input from the old Russian encoding KOI8-R to the locale encoding, substituting an angle bracket notation with hexadecimal numbers for invalid bytes and for valid but unconvertible characters. Chef's kiss formatting, honestly. 🔥

iconv --list

lists the supported encodings. Short king. 👑

💜 CONFORMING TO 💜

POSIX:2024

🍓 SEE ALSO 🍓

iconv_open(3), locale(7)

🌸 Big slay energy to the GNU girlies — this page is from GNU, dated December 15, 2024, and that's the whole manual page ICONV(1), start to finish. Go convert something, bestie. 💖✨🎀
📦 where this page comes from