ICONVCTL(3)

📦 version 1.19, in arch rolling

iconvctl 💅

Library Functions Manual realness, bestie! okay so this page is all about iconvctl and how it lets you poke at the behavior of a conversion descriptor. No cap, it's giving very much "control room for iconv" energy. 🎛️✨

✨ NAME ✨

iconvctl — control iconv behavior. periodt. 💅

🌸 SYNOPSIS 🌸

#include <iconv.h>

int iconvctl (iconv_t cd , int request, void * argument);

🦋 DESCRIPTION 🦋

okay so the cd argument has to be a conversion descriptor, and you get one of those by calling iconv_open. no random cd allowed, bestie. 🫶

iconvctl queries or adjusts the behavior of the iconv function when it's invoked with that specified conversion descriptor. what exactly happens depends on the request value. it's giving "same descriptor, different vibe check" energy. 🔥

💜 REQUEST VALUES 💜

The following are permissible values for the request parameter. get into it:

  • ICONV_TRIVIALP — argument should be an int * that will receive 1 if the conversion is trivial, or 0 otherwise. literally a yes/no moment. 💀
  • ICONV_GET_TRANSLITERATE — argument should be an int * that will receive 1 if transliteration is enabled in the conversion, or 0 otherwise. transliteration status check, slay. ✨
  • ICONV_SET_TRANSLITERATE — argument should be a const int *, pointing to an int value. a non-zero value is used to enable transliteration in the conversion. a zero value disables it. toggle time, bestie. 🎀
  • ICONV_GET_DISCARD_INVALID — argument should be an int * that will receive 1 if "discard invalid multibyte sequence from the input and continue" is enabled in the conversion, or 0 otherwise. 👀
  • ICONV_SET_DISCARD_INVALID — argument should be a const int *, pointing to an int value. a non-zero value is used to enable "discard invalid multibyte sequence from the input and continue" in the conversion. a zero value disables it. 🫡
  • ICONV_GET_DISCARD_NON_IDENTICAL — argument should be an int * that will receive 1 if "discard character that cannot be represented in the target character set and continue" is enabled in the conversion, or 0 otherwise. that's the vibe check for non-identical characters. 🦋
  • ICONV_SET_DISCARD_NON_IDENTICAL — argument should be a const int *, pointing to an int value. a non-zero value is used to enable "discard character that cannot be represented in the target character set and continue" in the conversion. a zero value disables it. 🌸
  • ICONV_GET_DISCARD_ILSEQ — argument should be an int * that will receive 1 if both "discard" behaviours are enabled in the conversion, or 0 otherwise. both, bestie. not one, not the other — both. 👑
  • ICONV_SET_DISCARD_ILSEQ — argument should be a const int *, pointing to an int value. a non-zero value is used to enable both "discard" behaviours in the conversion. a zero value disables them. double toggle energy. 🔥
  • ICONV_GET_FROM_SURFACE — argument should be an unsigned int * that will receive the from-side (input side) surface of the conversion. input-side surface reveal. 🌈
  • ICONV_SET_FROM_SURFACE — argument should be a const unsigned int *, pointing to an unsigned int value. this value is installed as the from-side (input side) surface of the conversion. the value is a bit mask. zero denotes no surface. the value ICONV_SURFACE_EBCDIC_ZOS_UNIX has an effect on EBCDIC encodings: the EBCDIC newline 0x15 will get mapped to LF instead of NEL. iconic bit-mask behavior. 🧚
  • ICONV_GET_TO_SURFACE — argument should be an unsigned int * that will receive the to-side (output side) surface of the conversion. output-side surface reveal. ⭐
  • ICONV_SET_TO_SURFACE — argument should be a const unsigned int *, pointing to an unsigned int value. this value is installed as the to-side (output side) surface of the conversion. the value is a bit mask. zero denotes no surface. the value ICONV_SURFACE_EBCDIC_ZOS_UNIX has an effect on EBCDIC encodings: LF, instead of NEL, will get mapped to the EBCDIC newline 0x15. another iconic bit-mask moment. 💜

🎀 RETURN VALUE 🎀

the iconvctl function returns 0 if it succeeds. in case of error, it sets errno and returns -1. so yeah, success is the 0 moment, error is the -1 plus errno situation. no cap. 😭

🔥 ERRORS 🔥

The following errors can occur, among others:

  • EINVAL — the request is invalid. wrong request, bestie. that's a no from the conversion descriptor. 🙈

👑 CONFORMING TO 👑

this function is implemented only in GNU libiconv and not in other iconv implementations. it is not backed by a standard. you can test for its presence through (_LIBICONV_VERSION >= 0x0108). iykyk. 💅

🌈 SEE ALSO 🌈

xoxo, GNU — December 15, 2024 🎀✨

📦 where this page comes from