Refresh the GdkPixbuf Loader Cache Safely

You will inspect the GdkPixbuf loader directory, generate loader metadata, and know when the system cache needs an administrator. The examples use gdk-pixbuf-query-loaders from GdkPixbuf 2.42.10, supplied here by libgdk-pixbuf2.0-bin version 2.42.10+dfsg-3ubuntu3.3.

Allow about ten minutes. You need a shell and the GdkPixbuf binary package. The inspection steps are read-only. Updating the shared cache changes system state and normally needs elevated privileges, so do not run that step until you have confirmed the module directory and the intended result.

1. Find the installed command and its cache

On this installation the command is not on the ordinary PATH. Locate it through the package contents, then record the cache path that GdkPixbuf uses by default:

$ dpkg-query -W -f='${Package} ${Version}\n' libgdk-pixbuf2.0-bin
libgdk-pixbuf2.0-bin 2.42.10+dfsg-3ubuntu3.3
$ dpkg -L libgdk-pixbuf2.0-bin | grep '/gdk-pixbuf-query-loaders$'
/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/gdk-pixbuf-query-loaders
$ stat -c '%A %U:%G %n' /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache
-rw-r--r-- root:root /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache

Your architecture or package revision can produce a different library path. Use the path printed by dpkg -L in the remaining examples. The manual calls the destination $libdir/gdk-pixbuf-2.0/2.10.0/loaders.cache; the 2.10.0 directory is the loader ABI version, not necessarily the installed GdkPixbuf release.

2. Inspect the modules without changing anything

Run the binary with no arguments. It scans the default loader directory and writes the generated cache text to standard output:

$ /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/gdk-pixbuf-query-loaders | sed -n '1,14p'
# GdkPixbuf Image Loader Modules file
# Automatically generated file, do not edit
# Created by gdk-pixbuf-query-loaders from gdk-pixbuf-2.42.10
#
# LoaderDir = /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders
#
"/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders/libpixbufloader-ani.so"
"ani" 4 "gdk-pixbuf" "Windows animated cursor" "LGPL"

Do not edit this output by hand. It contains each module's path, supported formats and MIME types in the format GdkPixbuf expects. The list is host-specific, so the exact modules and ordering can differ.

3. Query one module explicitly

Arguments are treated as module paths. They can be absolute or relative, and supplying one limits the query to the modules you name. This is useful for checking a newly installed loader without replacing the system cache:

$ loader=/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders/libpixbufloader-ani.so
$ /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/gdk-pixbuf-query-loaders "$loader" | sed -n '1,10p'
# GdkPixbuf Image Loader Modules file
# Automatically generated file, do not edit
# Created by gdk-pixbuf-query-loaders from gdk-pixbuf-2.42.10
#
"/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders/libpixbufloader-ani.so"
"ani" 4 "gdk-pixbuf" "Windows animated cursor" "LGPL"

If a module cannot be opened, the command reports a g_module_open() failure and still prints the cache header. Treat that as a failed inspection, not as a valid cache. Check the path with ls -l and confirm that the file is a loader shared object from the expected package.

4. Test a non-standard loader directory

GDK_PIXBUF_MODULEDIR overrides the directory scanned when no module paths are supplied. This lets you test path selection without touching the shared cache:

$ GDK_PIXBUF_MODULEDIR=/var/empty \
  /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/gdk-pixbuf-query-loaders
# GdkPixbuf Image Loader Modules file
# Automatically generated file, do not edit
# Created by gdk-pixbuf-query-loaders from gdk-pixbuf-2.42.10
#
# LoaderDir = /var/empty

An empty result is expected for an empty directory. The environment variable affects this process only. It does not move modules and does not alter the default cache. When an application must read a cache at a non-standard location, use GDK_PIXBUF_MODULE_FILE to point that application at the generated file.

5. Update the shared cache deliberately

Once the inspection output names the correct loader directory, update the default cache with the command's only option:

$ sudo /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/gdk-pixbuf-query-loaders --update-cache

--update-cache writes to the default cache location rather than standard output. It is the state-changing step and sudo is needed here because the installed cache is owned by root. Do not use it just to see what the command would generate. There is no dry-run form in this utility, so use the no-argument inspection command in step 2 first.

Verify the file after the command returns:

$ stat -c '%s bytes %U:%G %n' /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache
... bytes root:root /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache
$ sed -n '1,8p' /usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0/2.10.0/loaders.cache

The byte count and module list are installation-specific. The file should begin with the generated-file comments and a loader directory matching the modules you intended to scan.

6. Recover from a bad path or cache

If applications stop recognising an image format after an update, first inspect the cache and loader directory. Do not delete the cache as a first response: that can remove the metadata applications need. Re-run the no-argument query, correct GDK_PIXBUF_MODULEDIR if it is set, and then run --update-cache again with the correct environment.

If you deliberately generated a cache somewhere else for an application, point that application at it with GDK_PIXBUF_MODULE_FILE=/path/to/loaders.cache. Remove that temporary environment setting when testing the normal system configuration. The utility does not provide an undo command; recovery is regeneration from the installed loader directory, not hand-editing the cache.