List X Toolkit Widget Resources with listres

When a Motif or Athena app ignores your resource file, listres tells you what the widget actually accepts instead of leaving you to guess. It prints the resource hierarchy an X Toolkit application knows about, and you can narrow it to one widget family or strip out inherited noise so the report is worth reading. Allow about ten minutes.

You need the x11-utils package and an X display the command can reach. Nothing here changes a resource or an application setting: it only reads the widget definitions compiled into the program.

The examples describe the installed command on this machine: x11-utils 7.7+6build2, whose manual identifies the program as listres 1.0.5. The output depends on the widget set compiled into the program, so your list can differ from these examples.

1. Confirm the package and the display

Check the executable exists and the shell knows which display to talk to:

$ command -v listres
/usr/bin/listres
$ printf '%s\n' "$DISPLAY"
:0

The display value above is just an example: use whatever your desktop session, remote X connection or SSH forward actually set. An empty $DISPLAY is the usual reason behind Can't open display:, and no amount of guessing display numbers fixes that. You need the value that belongs to the X session you're inspecting.

Checkpoint: if command -v prints nothing, install x11-utils the normal way. If DISPLAY is empty, sort out access to the X server first. sudo will not fix either problem; it does not grant your account access to an X server it can't already reach.

2. Print the default widget hierarchy

Run listres with no widget selector and it dumps the whole known catalogue:

$ listres
Widget Name                 Widget Class Hierarchy
------------                ---------------------
core                        Core
object                      Object
rectObj                     RectObj
...

The rows depend entirely on the widget set compiled into your build, so yours will not match this example line for line. Without -all and no specific widget named, you get a two-column list of names and class hierarchies: a catalogue, not the live resource values of a running application.

If your display isn't picked up from the environment, say so explicitly with the standard X Toolkit option:

$ listres -display "$DISPLAY"

Keep the quotes around "$DISPLAY": they preserve the display name exactly as the session gave it to you.

3. Get resource definitions for every known widget

Add -all when you want the resource database for every widget and object the binary knows about:

$ listres -all > listres-all.txt
$ test -s listres-all.txt && echo 'resource report written'
resource report written

This writes to a new file and touches nothing in the X session. Each line names the class where a resource was first defined, its instance and class names, and its type. Redirect it: the full report is far longer than the default catalogue and scrolling through a terminal is a waste of your time.

$ sed -n '1,30p' listres-all.txt

Keeping it as a separate file means you can never accidentally change the resource database while reading it.

4. Compare a subclass against its inherited resources

Sometimes the question isn't "what does this widget have" but "what does it add". -nosuper answers that by dropping anything inherited from the superclass:

$ listres -nosuper -top core > core-new-resources.txt
$ test -s core-new-resources.txt && echo 'subclass-only report written'
subclass-only report written

-top name sets where the hierarchy starts. Matching is case-insensitive and works against either the class variable name or the class name; the default top is core.

A short or empty report here is not proof of a broken widget. It usually just means the hierarchy has nothing new below its superclass, or the display could not be opened before the report ran. Check the exit status to tell those apart:

$ listres -nosuper -top core > core-new-resources.txt
$ status=$?
$ printf 'listres exit status: %s\n' "$status"
listres exit status: 0

5. Tell apart classes that share a name

Some subclasses reuse their superclass's class name, which makes a plain listing ambiguous. Add -variable to identify widgets by their class record variable names instead:

$ listres -all -variable > listres-by-variable.txt
$ grep -n 'Widget\|Class\|resource' listres-by-variable.txt | sed -n '1,12p'

The exact headings shift with the formatter and installed widget set, so treat that grep as a quick orientation pass rather than something to parse in a script. If you're building a durable check, keep the raw report alongside the command that generated it.

6. Format the report for another tool

-format printf-string controls how each resource line is printed, receiving the resource name, instance name, class name and type:

$ listres -format '%s %s %s %s\n' > resources.tsv

The format is printf-style, so the usual printf risks apply: a wrong conversion or missing quoting turns the output into gibberish. Start with the four documented string conversions, check a few lines, then adapt. There's no header row, so don't assume resources.tsv is a well-formed tabular file on its own.

Common traps

A missing or wrong $DISPLAY fails before any widget output appears. Verify it and retry against the same session:

$ printf 'DISPLAY=%s\n' "$DISPLAY"
DISPLAY=:0
$ listres -display "$DISPLAY" > /tmp/listres-check.txt
$ printf 'status=%s\n' "$?"
status=0

Warning: do not reach for sudo listres as a blind fix if it still fails. Root may have a different DISPLAY or X authority, and forcing access control open can expose the session to other users. A clean exit status only means the report generated, not that a widget application's live values are correct.

Tip: keep generated reports around if you're mid-investigation. When you do clean up, check the exact path first: rm -- listres-all.txt deletes it permanently and there's no undo.

Done means