iconvconfig

iconvconfig [OPTIONS]

--output=FILE or -o FILE
    Specifies the output cache file. By default, it writes to the system's standard iconv cache location.

--add-dir=DIRECTORY or -r DIRECTORY
    Adds DIRECTORY to the list of directories scanned for gconv modules.

--clean or -c
    Removes old gconv modules that are no longer referenced in the configuration.

--prefix=PATH
    Uses PATH as the prefix for searching module directories and the default cache file.

--sysconfdir=DIR
    Specifies the system configuration directory. Used to find the main gconv-modules definition file.

--verbose or -v
    Enables verbose output, showing more details about the process.

--silent or -s
    Suppresses all non-error output.

--version
    Displays the version information of iconvconfig.

--help
    Shows a help message and exits.

iconvconfig is a utility used to manage and rebuild the iconv character set conversion cache file, typically named gconv-modules.cache.

This cache file is crucial for the iconv function (part of the GNU C Library, glibc) to efficiently locate and perform character encoding conversions between different character sets (e.g., UTF-8, ISO-8859-1, EUC-JP).

When new character set modules are installed, or the system's glibc is updated, iconvconfig should be run to regenerate this cache. It scans predefined directories, like /usr/lib/gconv, for available conversion modules (.so files) and their definitions, then compiles this information into a quick-lookup cache.

Running iconvconfig ensures that all installed character set conversions are recognized and available for applications using iconv, preventing potential errors or incomplete conversions due to missing module information. It's usually invoked automatically by package managers when glibc or related locale packages are updated.

Running iconvconfig typically requires root privileges as it modifies system-wide configuration files in directories like /usr/lib/gconv.
Incorrect usage or interruption during its execution could potentially corrupt the iconv cache, leading to character set conversion failures for applications on the system.
It is usually invoked automatically by package management systems after glibc updates or installation of new locale packages, so manual intervention is rarely needed unless issues arise.

The primary file managed by iconvconfig is the gconv-modules.cache (or iconv.cache on some systems), typically located in /usr/lib/gconv or /usr/local/lib/gconv. This binary cache file allows iconv functions to quickly look up available character set conversions without parsing text configuration files each time, significantly improving performance.

While iconvconfig can be run manually, it is most often executed automatically by package managers (e.g., apt, dnf, pacman) as part of post-installation scripts for glibc or locale-related packages. This ensures the iconv cache is always up-to-date with the installed character set modules.

The iconvconfig utility is an integral part of the GNU C Library (glibc), which provides fundamental system calls and library functions for Linux. Its development is intertwined with the evolution of glibc's internationalization (i18n) and localization (l10n) support.

The underlying iconv framework itself is based on POSIX.1-2001 and XPG4 specifications, aiming to provide a standardized way for applications to convert text between different character encodings.

iconvconfig emerged as a necessary tool to manage the dynamic loading and caching of these conversion modules, ensuring efficient and robust character set conversion capabilities across the system as new locales and encoding standards were introduced and updated.

iconv(1), localedef(1), locale(1), gconv(3)