Rebuild the glibc iconv Module Cache Safely

Every process that calls iconv(3) reads glibc's gconv cache, and iconvconfig rebuilds it when a stale one quietly breaks conversion. This walks through testing that rebuild in a temporary file first. Examples match the Ubuntu glibc 2.39 installation used here. Set aside about 10 minutes, plus time to check any package or service that owns custom conversion modules.

Before you start

• This is an administration task. You need the iconvconfig program, normally supplied by the libc-bin package, and read access to the gconv configuration directory.
• A normal user can build a cache with --output in a writable directory.
• Writing the installed cache requires root and can affect programs that use iconv(3).

Check the program and locate the active files before copying a command below. The manpage describes /usr/lib/gconv and /usr/lib64/gconv as usual locations, but multi-architecture systems may use a path such as /usr/lib/x86_64-linux-gnu/gconv.

command -v iconvconfig
iconvconfig --version
find /usr/lib /usr/lib64 -path '*/gconv/gconv-modules' -type f -print 2>/dev/null

On this machine the version output begins iconvconfig (Ubuntu GLIBC 2.39-0ubuntu8.9) 2.39, and the active directory is /usr/lib/x86_64-linux-gnu/gconv. Use whatever directory you find on your own host in the commands that follow.

1. Understand what will be read

List the directory and inspect the main configuration file. It must contain either a gconv-modules file or a gconv-modules.d directory holding configuration files ending in .conf. The cache itself is binary, so opening it in an editor tells you nothing useful:

gconv_dir=/usr/lib/x86_64-linux-gnu/gconv
ls -ld "$gconv_dir" "$gconv_dir/gconv-modules" "$gconv_dir/gconv-modules.cache"
sed -n '1,24p' "$gconv_dir/gconv-modules"
find "$gconv_dir/gconv-modules.d" -maxdepth 1 -type f -name '*.conf' -print 2>/dev/null

Tip: do not confuse GCONV_PATH with a cache location. When GCONV_PATH is set, glibc skips iconv module configuration caching entirely, so a shell, service unit or wrapper that exports it can make a freshly rebuilt cache look ineffective.

2. Build a disposable cache

Use --nostdlib to make the command read only the directory named on the command line. --output writes somewhere other than the installed cache, and is the safest way to check that the configuration parses. This step changes only the temporary file:

gconv_dir=/usr/lib/x86_64-linux-gnu/gconv
test_cache=/tmp/gconv-modules.cache.test
iconvconfig --nostdlib --output="$test_cache" "$gconv_dir"
status=$?
printf 'iconvconfig exit status: %s\n' "$status"
test "$status" -eq 0 && stat -c '%s bytes %n' "$test_cache"

Checkpoint: expect exit status 0 and a non-empty file. With the installed directory on this host, the test cache is 27028 bytes; your size can differ when glibc or the module set differs. A diagnostic about a missing gconv-modules or gconv-modules.d means the directory is wrong or incomplete, so fix that input rather than writing an empty replacement cache.

3. Update the installed cache only when required

Rebuilding the default cache is a privileged, shared-system change. Stop after step 2 if you only needed to validate a custom module directory. If package maintenance or a deliberate configuration change genuinely needs the installed cache, take a copy first and run the command as root with the directory you already verified:

gconv_dir=/usr/lib/x86_64-linux-gnu/gconv
sudo cp -p "$gconv_dir/gconv-modules.cache" /tmp/gconv-modules.cache.before
sudo iconvconfig "$gconv_dir"
printf 'iconvconfig exit status: %s\n' "$?"
stat -c '%s bytes %n' "$gconv_dir/gconv-modules.cache"

The command has no useful text output on success, so its exit status is the checkpoint. Do not add --nostdlib here unless you intentionally want to exclude the system default directories, and do not assume --prefix applies to an explicit --output file: the installed program's help states plainly that it does not.

Recovery: if the new installed cache causes a problem, restore the backup made above, then investigate the module configuration before trying again:

gconv_dir=/usr/lib/x86_64-linux-gnu/gconv
sudo cp -p /tmp/gconv-modules.cache.before "$gconv_dir/gconv-modules.cache"
stat -c '%s bytes %n' "$gconv_dir/gconv-modules.cache"

Useful alternatives and traps

• iconvconfig --help or --usage checks syntax without touching a cache. --version reports the glibc version, licence and warranty notice.
• -o FILE is the short form of --output=FILE. An explicit output path must be writable by the current user, or by root when using sudo.
• --prefix=PATH is for a staged filesystem tree. With a prefix of /srv/stage, the program looks for configuration below /srv/stage/usr/lib/gconv and writes the corresponding cache there, unless an explicit output path is given.
• Keep the directory argument when testing with --nostdlib: without it, the command has nothing left to scan once the standard search is disabled.

Done means

• iconvconfig --version identified the installed glibc release.
• The selected gconv directory contains valid configuration input.
• A disposable cache was created with exit status 0.
• GCONV_PATH is not unexpectedly bypassing the cache.
• If the shared cache was changed, its size was checked and the original was backed up for recovery.