Eterm FAQ

What documentation is provided with Eterm?

What's new in the latest version of Eterm?

How do I fix my Backspace and Delete keys?

How can I bind keys in Eterm?

What is "auto" mode, and how do I use it?

How do I use color modifiers?

What is this new menubar thing, and how do I configure it?

Actually, I just want it to go away. How do I turn the buttonbar off?

Where are all these random backgrounds coming from? How do I turn them off?

Why doesn't Eterm read my shell profile/rc files (.bashrc, .bash_profile, etc.)?

Frequently-Asked Questions about Eterm

What documentation is provided with Eterm?

Here is a list:

  • doc/Eterm_reference.html -- This technical reference is intended for advanced users.
  • doc/Eterm.tcap -- Termcap entry for BSD systems.
  • doc/Eterm.ti -- Terminfo database entry.
  • doc/Eterm.1 -- The man page is installed by default.
  • src/feature.h -- Header file containing some compile-time configuration options.
  • bg/README.backgrounds -- Information and credits for the background collection.
  • ReleaseNotes -- Highlights and important notes for each release.
  • README -- Instructions for compiling and installing Eterm.
  • Eterm.spec -- Spec file for building RPM's.
  • ChangeLog -- A per-commit record of changes made to Eterm over the course of its development.

What's new in the latest version of Eterm?

Eterm 0.9.6 is a bugfix and security release.

Enhancements to Eterm 0.9.6 over previous versions include:

  • Speed-ups on load from removal of unnecessary fontset fallbacks.
  • Corrected erroneous disabling of SIGPIPE in child processes.
  • Fix for FreeBSD UNIX98 pty support.
  • Fix for scrolling limitations.
  • Support font effects in all 8 directions.
  • No longer doing borderless via override_redirect.
  • Fixed a crash with visual bell.
  • Fix for CVE-2011-0409 (CERT VU#285156), a use-after-free error in the XIM code. This only affects versions where XIM support is compiled in (which it is by default). There are no known exploits for this bug, but it is theoretically exploitable. Thanks to Jonathan Brossard and the team at Toucan System for responsibly disclosing this vulnerability and to CERT for assisting with coordination and disclosure.
  • Fix for CVE-2011-0768, an off-by-one error in handling large pixmap filenames which resulted in an overflow of a single NUL character if the filename exceeded PATH_MAX bytes. This bug is NOT exploitable. Again, thanks to Jonathan Brossard and the team at Toucan System for responsibly disclosing this vulnerability and to CERT for assisting with coordination and disclosure.

How do I fix my Backspace and Delete keys?

Translating keys pressed on the keyboard into the desired response from your applications is a surprisingly involved process. There are several layers of translation involved here, and a mistake by any one of them can result in undesired behavior. So here's a brief tutorial on how to figure out where the problem lies.

The first step in the translation process involves turning a keycode (as emitted by your keyboard in response to a keypress) into a keysym (a symbolic entity in X which represents the various keys which can exist). To figure out which keysyms correspond to which keycodes (and therefore, which keystrokes), use xmodmap -pk. This command will display all 255 keycodes and the keysym which corresponds to each one. Keysyms are represented as both 16- and 32-bit integers, and as symbolic names. For example, you might see 0xff1b (Escape) in your listing. This means that the keysym 0xff1b should correspond to the pressing of the ESC key.

For the purposes of this discussion, we are interested in two keysyms specifically: Backspace (0xff08) and Delete (0xffff). On my keyboard, as well as most US keyboards (87-, 101-, and 104-key models), keycode 22 is sent by the "Back Space" key and should therefore correspond to the Backspace (0xff08) keysym. Similarly, keycode 107 is sent by the "Del" key and should therefore match up with the Delete (0xffff) keysym. Check the output of the xmodmap command above to see if those match up.

If you have a different keyboard, or if you simply want to make certain you've got the right keycodes, use the X Event Viewer (xev) utility. It will show you the keycode and keysym for each key you press. Make sure that when you hit the "Back Space" key it brings up the Backspace keysym. Likewise for the "Del" key and the Delete keysym. If they do not match up, you can also use xmodmap to remap those keycodes to the proper keysyms. For example, if your "Back Space" key is indeed keycode 22 but is sending the "Delete" keysym instead, the following command will correct the problem: xmodmap -e "keycode 22 = 0xff08". This will cause keycode 22 to correspond to the Backspace (0xff08) keysym as it should. The command for matching up the "Del" key would be very similar: xmodmap -e "keycode 107 = 0xffff".

At this point, I will assume you have gone through the above steps and have the proper keycodes matching up with the proper keysyms. This is where Eterm comes in. Eterm uses keysyms to turn KeyPress events into the letters, numbers, or character sequences to which they correspond. For example, when you hit the 'A' key, Eterm receives a KeyPress event and the keysym "XK_A" (0x0041) to represent which key was pressed. It then asks the X server for the string associated with that keysym; it receives "A" as a reply from the server, and therefore sends that string on to the pty device and your shell. However, some keys are treated specially by Eterm (e.g., function keys); it does not query the X server for these keys, but rather recognizes them by keysym and sends the proper string itself.

Because there are so many possibilities here, Eterm tries to offer the user maximum flexibility in what it sends for these keys. For example, the Backspace keysym can be made to send the BS character (^H), the DEL character (^?), or rely on the X server to have the proper value. Similarly, the Delete keysym can be mapped to the DEL character (^?), the Execute escape sequence, or the X server value. However, now that Eterm has its own terminfo entry (as of Eterm 0.9.1 and ncurses 5.2), the standard settings (BS and Execute, respectively) should most likely not be altered. Should you wish you alter them anyway, consult the help for the configure script.

Applications which are based on curses (or one of its derivatives) use the termcap/terminfo databases to translate character strings and escape sequences into their actual meanings. However, "dumb terminal" applications (like cat) use stty settings to determine Backspace mappings. Based on what Eterm is sending for the "Back Space" key (which you can determine using the 'cat' command if it isn't working for you), use the command stty erase ^H or stty erase ^? to properly map that key. This command is best placed in the appropriate config file for your shell.

How can I bind keys in Eterm?

All keybindings in Eterm are based on the concept of keysyms. (See the question above for more info on keysyms.) To bind a key with Eterm, its keycode must correspond to a valid keysym. You can use the xmodmap command as shown above to map keycodes to keysyms.

Once the key sends a valid keysym, you can have Eterm recognize and respond to it in a particular way using action bindings. The man page discusses the syntax in depth, so I won't do that here. I'll just demonstrate with a few examples.

 begin actions
     # Force the backspace key to send ^H
     bind 0xff08 to echo '^H'
     # Make the mail key open mutt
     bind 0x1008ff19 to script 'exec(Eterm -t mutt)'

What is "auto" mode, and how do I use it?

Auto mode is an option in 0.9 Eterm, where Eterm queries Enlightenment for a set of images to use for the scrollbars, background, and so on. Eterm does not control the images at all. Eterm doesn't even draw the images, Enlightenment does. Because of these facts, you cannot change the contrast, gamma, or anything else within Eterm, since it doesn't control the image. If you want the image to be a little darker or lighter, then you'll need to alter the images within your Enlightenment theme.

In order for Eterm to use auto mode, it needs a certain set of imageclasses from the Enlightenment theme you are running. (Enlightenment 0.16's Brushed Metal theme has all the imageclasses defined for auto mode, if you wish to see an example.) Here is a list of the imagesclases, and what they represent:

ETERM_BG Background image
ETERM_ARROW_LEFT Left arrow (for possible future use)
ETERM_ARROW_RIGHT Right arrow (for possible future use)
ETERM_TROUGH Scrollbar trough
ETERM_ANCHOR Scrollbar anchor
ETERM_THUMB Scrollbar thumb
ETERM_MENU_BOX * Menu background
* Currently, ETERM_MENU_BOX doesn't work; Eterm uses ETERM_MENU_ITEM instead.

Eterm comes with a theme called "auto" which is exactly like the "Eterm" theme except that it uses auto mode by default. You should be able to simply run Eterm -t auto to get auto mode. If not, keep reading for how to activate it yourself.

If you look through the theme files (theme.cfg), you'll find a "mode" line for each image that looks something like this:

    mode image allow image trans viewport auto

The first word is always "mode." This defines the "current" mode, which is the mode that particular imageclass should use on startup. Valid modes are: "image" to use an image file, like a JPEG; "trans" to be transparent; "viewport" for viewport mode; "solid" for a solid color; and "auto" for auto mode. This is followed by the word "allow" and a list of all the modes the imageclass is allowed to use. As a shortcut, you may omit the "current" mode from the "allow" list; it will be added automatically.

So to activate auto mode, you'd change the "mode" line for each imageclass to:

   mode auto allow image trans viewport auto

One last note. The "solid" mode is a fallback, so it is always allowed, whether you specify it or not, and cannot be disallowed.

How do I use color modifiers?

The traditional --shade and --tint options are actually ways of manipulating "color modifiers." Color modifiers are sets of brightness, contrast, and gamma corrections which alter those qualities of the image. Each image has 4 color modifiers: one for the image as a whole, and one for each color (red, green, and blue). The shade option actually alters the brightness element of the image color modifier, and the tint option alters the brightness element of the red, green, and blue color modifiers. There is, however, no shortcut to modifying the gamma and contrast factors.

Since there are 4 color modifiers per imageclass, there are 4 different options through which you can manipulate the color modifiers. The image color modifier, or "cmod" for short, is accessed via the --cmod command-line option. The red cmod is altered using the --cmod-red option, the green via the --cmod-green option, and the blue via the --cmod-blue option.

You can pass either 1, 2, or 3 unsigned positive integers to each of these options; these numbers can be in decimal, octal (preceded by a leading 0), or hexadecimal (with a leading 0x). The first number represents the brightness factor, the second the contrast factor, and the third the gamma factor. Keep in mind that each of these three factors acts like a percentage, but instead of being based on 100 (where 100 means 100%, or "no change"), the cmod elements are based on 256. So 0 still means 0, but 256 means "no change" and 512 means "double" or "200%."

So, to get a cyan tint, you'd want to reduce the brightness of red (since blue and green make cyan). Thus, you might use:

   --cmod-red 128

This would give you a cyan-tinted shading effect. Of course, you can use any number less than 256 in place of the 128; the value of 128 is just an example.

If you wanted to brighten with a cyan tint instead of shading, you could use:

   --cmod-blue 298 --cmod-green 298

As above, the value of 298 is just an example. Anything above 256 will work, so adjust the number till you get an effect you like.

To shade/brighten the overall image rather than specific ranges of color, use the "image" cmod:

   --cmod <number>

where <number> is less than 256 for shading or greater than 256 for brightening.

If you wish to modify the contrast of the image, simply specify the brightness and contrast values you wish. Remember that you must specify the brightness if you want to alter the contrast. For example, if you want to increase the contrast a bit while keeping the brightness the same, you could use:

   --cmod "256 298"

Remember that you must pass both numbers to the --cmod option; thus, you will probably need to put quotes around them so that your shell passes them as a single parameter.

The examples above all demonstrate the syntax for the command line. You can also specify color modifiers for each imageclass in the config file using the "cmod" or "colormod" attribute:

   cmod image 0xE6 0x120
   cmod green 0xAA

This gives a 10% shade (90% brightness) to the image overall along with a 112% contrast and a slight magenta tint. Note that I used hexadecimal numbers here; you can do the same for the command line options if you wish, or you can use decimal numbers in the config file. Eterm doesn't care either way. (In fact, just about any number in the config file or on the command line can be specified in hex (with a leading "0x"), octal (leading "0"), or decimal (otherwise).)

What is this new menubar thing, and how do I configure it?

That is actually a buttonbar, not a menubar. It makes use of the new "button_bar" and "button" imageclasses to draw itself, and is completely user-configurable. The buttonbar can have as many buttons on it as can fit in the horizontal dimensions, and you can have as many buttonbars as you care to define. Each button can be bound to any of the same actions a menuitem or action binding can: a string to be parsed by Eterm, something to echo to the child process, a menu to display, or a script to execute.

In other words, if all you want is a menubar, you can do that. But you can also do much, much more. :-)

In addition, each button can have an icon, text, or both. The ? and X icon buttons in the default theme demonstrate this capability. They also demonstrate "rbuttons," buttons which are right- instead of left-justified. The following config file excerpt shows how a buttonbar is defined:

 begin button_bar
   button Eterm action menu "Eterm Operations"
   button Font action menu Font
   button Background action menu Background
   button Terminal action menu Terminal
   rbutton icon help.png action script "exec(Eterm -e man Eterm)"
   rbutton icon exit.png action script "exit()"
 end button_bar

Actually, I just want it to go away. How do I turn the buttonbar off?

Recall that Eterm supports multiple buttonbars. This means that each buttonbar context in the config file(s) defines a new buttonbar and has no effect whatsoever on any previously-defined buttonbars. Thus, you cannot alter the attributes of a buttonbar which is defined in theme.cfg by making changes to user.cfg.

Find the file in which the buttonbar is defined. This is most likely the theme.cfg file. In order to completely get rid of the buttonbar, you must delete this entire context from the config file. However, unless saving a few bytes of memory is a huge concern to you, the best thing for you to do is simply tell it not to be visible on startup. That way you can toggle it on later if and when you want it.

To do this, simply add a line that says "visible no" just above the font line. (Note to advanced users: The visible attribute, as you might suspect, is actually a boolean value, so any of the 4 acceptable values for false will work here. And you can place it anywhere within the context, not just as the first item.)

As a shortcut, the command line option --buttonbar 0 will set all your buttonbars to be invisible on startup.

Where are all these random backgrounds coming from? How do I turn them off?

The default themes all choose background pictures at random from the collection supplied with Eterm. The lines in the config file that activate this behavior are shown here:

 # Here you set the file.  You can also set the geometry string here if you follow the filename with
 # an @ sign.  That way, you can include the geometries in your pixmaps.list file.
       file %random(`cat pixmaps.list`)

Of course, the first two lines are merely comments. It's the third line that does the actual work. The backquotes are evaluated first to cat the pixmaps.list file and include its contents as the parameters to the %random() function. The function then picks one parameter at random and returns it. Thus, the name of the randomly-selected pixmap becomes the parameter to the file attribute. In order to deactivate this behavior, simply change this line to refer to a specific image file, or alter the mode line (just below the file line) to specify a mode other than image for the background.

Why doesn't Eterm read my shell profile/rc files (.bashrc, .bash_profile, etc.)?

Okay, let me make this very, very clear right off the bat.

Eterm DOES NOT read any shell profile/rc file for any shell. Ever. Never has, never will. Neither does any other terminal program. You are confused.

When Eterm starts up, it is provided with the environment of its parent process, be it your window manager, your X startup file, your panel/launcher application, or whatever. Eterm, in turn, spawns a subprocess which inherits its environment from Eterm itself. This subprocess is usually a shell, but can be anything you specify with the -e option. The shell itself is then responsible for parsing its OWN config files and bringing up your prompt, after which all programs you launch from that prompt inherit their environments from the shell running inside Eterm.

The difference between Eterm and other terminal programs is the fact that the default Eterm configuration is to spawn what is called a "login shell." In other words, Eterm prepends a hyphen ('-') to the shell name when calling it, just as the login process would do. Login shells generally behave slightly differently from non-login shells, specifically in terms of the files they read. This is almost certainly the source of the problem you're experiencing.

For example, bash will source .bash_profile for a login shell and .bashrc for a non-login shell. So if all your shell configuration settings are in .bashrc and you have an empty/missing .bash_profile, shells inside an Eterm will not have your settings.

99% of users do not need to distinguish between non-login and login shells. These users can simply symlink .bash_profile to .bashrc, or vice versa. Those few users who do need the distinction should put all login shell stuff in .bash_profile and all common content in .bashrc. Then, at the end of your .bash_profile, add the line:

      source ~/.bashrc

Make sure both files are executable, and you should be all set!


Copyright ©2001, Michael Jennings.   If you have any questions or comments, please e-mail me.