This is an article I submitted to a journal, but it was too short for their format.

Key Symbols in X

A common problem with X clients is specifying meaningful names for keys which may not be present on all keyboards, or which have different legends on different keyboards. These include keys specific to certain vendors, such as Sun's Props key, common operations such as backspace (which might be the BackSpace or the Delete key), and logical operations which may change according to user preference(such as OsfActivate and OsfPreviousMenu). These names are known as key symbols or keysyms.

While xmodmap(1) handles all manner of translations for existing keysyms, the keysymdb is primarily concerned with adding new keysyms (it understands previously-defined keysyms as well). Keycodes are server-specific, numeric codes assigned to actual keys on a given keyboard type, while keysyms are server-independent, logical mappings of symbols to the actual keycodes.

The most common keysyms map directly to typical key legends ('A' or 'Shift'), but the keysyms discussed here often do not (as in the OSF keys above). The former type of keysym is built into your X server; the latter type does not exist for your system unless defined via the keysymdb.

Keysym Database

The system default database file is normally /usr/lib/X11/XKeysymDB . If this file is not installed, applications requiring any such keys will generate error messages about missing keysyms. Xt-based apps (such as Motif clients) typically complain about translation bindings. The latter will always note the offending keysym.

As of X11R5, you may override the system keysymdb file, or supply your own, by setting the XKEYSYMDB variable to the path of the keysym file you wish to use. A common system location is /usr/local/lib/X11/XKeyymDB . A good user path is $USER/.xkeysymdb .

The keysymdb file is formatted as a standard Xrm resource file: lines beginning with '!' are comments, lines beginning with '#' should be #include statements (standard X11R5 does not support other C preprocessor directives in Xrm files except through the xrdb command), and all other (non-blank) lines must be of the format

resource_name : value

(whitespace is ignored) as in the example below.

! ~/.xkeysymdb
!
#include </usr/lib/X11/XKeysymDB>
!
! Delete should be Backspace for
! Cavenewt Super-3 workstation keyboards
!
!osfDelete
!osfBackspace
!
osfDelete       :<Key> Backspace
osfBackspace    :<Key> Delete
osfRight        :<Key> Right
SunProps        :1005FF70

The OSF virtual keysyms are an example of the sort of things the keysym database is for. The keysym database is not intended for more general translations, so complex mappings, such as Alt<Key>1 for Sun's L1 key are not possible. Use xmodmap for this.

Motif clients often require some subset of the OSF keysyms. The Motif window manager (mwm(1)) typcially handles translations for Motif clients. mwm loads the system bindings by default. If you use another window manager or prefer to override the defaults, use Motif's xmbind command.

Using Keysyms

Keysyms are used anywhere you might normally reference a key. Typically this will be in translation tables in resource files as in this excerpt from a modified xterm app-defaults file

Ctrl Shift <Key> OsfMenu:   popup-menu(mainMenu) \n\
Ctrl Meta <Key> OsfMenu:    popup-menu(tekMenu) \n\

or in configuration files such as the portion of an .mwmrc file shown below.

Keys DefaultKeyBindings
{
Ctrl Shift <Key> OsfMenu          root   f.menu   HostsMenu
Ctrl Meta <Key> OsfMenu           root   f.menu   RootMenu
Ctrl Shift Meta <Key> OsfDelete   root   f.exec   "/usr/local/adm/reboot"
}

Motif Specifics

Motif actually searches several places for keysym bindings, rather like the Xt Intrinsics search for resources:

An application resource (in the resource database) named defaultVirtualBindings.
A property on the root window (set by mwm on startup, by the xmbind client, or on prior startup of a Motif application).
The .motifbind file in the user's home directory.
A set of bindings in a file whose name is based on the vendor string and optionally the vendor release of the X server. Motif searches for these first in the file xmbind.alias in the user's home directory. If Motif cannot find this file or a pathname based on the strings mentioned above, it then seeks a system xmbind.alias file, first in the directory sepcified in the environment variable XMBINDDIR (if any), or in the /usr/lib/Xm/bindings directory. If it finds this file, it again tries to build a path name from the strings mentioned above, and looks for the bindings there. If all else fails, Motif uses hard-coded bindings as a fallback.

More Information

Your server vendor should provide you with the basic bindings you need. Motif should also come with bindings for for the OSF-specific keysyms.

For further reading on keysyms in general, see the X(1) man page, and the chapter on "Setup Clients" in Volume 3 of O'Reilly's Guide to the X Window System. You can find more information on Motif bindings in the Motif VirtualBindings(3) man page.

Last updated: 10 July 1996

Miles O'Neal <roadkills.r.us@XYZZY.gmail.com> [remove the "XYZZY." to make things work!] c/o RNN / 1705 Oak Forest Dr / Round Rock, TX / 78681-1514