Frequently-Asked Questions about 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
- bg/README.backgrounds -- Information and credits for the
- 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.
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
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.
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
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.
# 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)'
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
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:
||Left arrow (for possible future use)
||Right arrow (for possible future use)
* Currently, ETERM_MENU_BOX doesn't work; Eterm uses ETERM_MENU_ITEM
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
So to activate auto mode, you'd change the "mode" line for each
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.
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
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:
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:
where <number> is less than 256 for shading or greater than 256
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
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
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
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:
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()"
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
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.
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.
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:
Make sure both files are executable, and you should be all set!