gpm: gpm-root
5.4 The "gpm-root" program
==========================
The program 'gpm-root' is designed to handle Control-Mouse events to
draw menus on the background of the current tty. The actual menus are
described by a configuration file in the user's home directory.
Please note that 'gpm-root' needs to run with Linux 1.1.73 or newer,
because previous kernels lack some screen handling capabilities required
by the program.
The program uses the files '/dev/vcs*' to draw to the console screen.
These are available only from kernel 1.1.81 onward. If you miss those
device nodes, you should create them using 'create_vcs' in the
distribution directory. The tool won't run with kernels older than
1.1.81, because they lacked a full screen dump/restore capability.
Available command line options are the following:
'-m NUMBER'
Choose the modifier to use (by default: 'control'). The modifier
can be provided either as a number or as a symbolic string.
Allowed strings are 'shift', 'anyAlt', 'leftAlt', 'rightAlt',
'control'.
'-u'
Deny using user-specific configuration files. With this option on,
only '/etc/gpm/root.conf' will be used as a source of configuration
information. This option is intended for those system
administrators who fear security could be broken by this daemon.
Things should be sufficiently secure, but if you find a hole please
tell me about it.
'-D'
Do not automatically enter background operation when started, and
log messages to the standard error stream, not the syslog
mechanism. This is useful for debugging; in previous releases it
was done with a compile-time option.
'-V VERBOSITY INCREMENT'
Raise the maximum level of messages that will be logged. Thus a
positive argument has the effect of making the program more
verbose. One can also give a negative argument to hush the
program; however, note that due to getopt(3) rules a negative
argument must follow the option with no space betwixt (that is,
'-V-1' but not '-V -1'). 
(libc)Program Arguments. The
argument is optional and its default value is 1.
Each time a menu is drawn, the configuration file is reparsed if it
has changed. This allows modification of personal setup without
reinvoking the daemon.
The actual configuration file is better introduced by an example:
# sample configuration file for gpm-root
# edit it to suit your taste
button 2 {
name "system status"
foreground red
background black
border yellow
head bright yellow
"" f.nop
"load: " f.load
"free:" f.free
"---------" f.nop
"disk usage" f.bgcmd "du | sort -rn > /tmp/du"
}
button 3 {
name "jump"
foreground black
background red
border bright yellow
head bright yellow
"tty1" f.jptty "1"
"tty2" f.jptty "2"
"tty3" f.jptty "3"
"tty4" f.jptty "4"
"tty5" f.jptty "5"
"tty6" f.jptty "6"
"" f.nop
"more of them..." {
"tty 17" f.jptty "17"
}
}
The syntax for the file won't be described here, being it quite
apparent from the example above. Blanks and newlines are unused in
parsing the file, and the layout of the file is free. Comments are
allowed in the file: any hash mark ('#') found at the beginning of the
line or after white space makes the parser discard anything up to the
next line. To insert quotes ('"') in strings precede them with a
backslash.
Note that recursive menus are allowed, to any level of recursion.
Keywords belong to three groups: the button keyword, the cfg keywords
and the action keywords. They are all described in the table below:
'button NUMBER MENU'
The 'button' keyword is used to introduce a menu. It is followed
by the number of the relevant button (1=left, 2=middle, 3=right),
an open brace, a menu and a closed brace. A menu is made up of cfg
statements, followed by action statements. Cfg statements can come
in any order, while the order of action statements tells the actual
order in which actions will appear on the screen, top to bottom.
The following statements belong to the cfg set.
'name STRING'
If the 'name' keyword is present, the specified STRING will be used
as the name for the current menu.
'background COLOR'
This statements is used to specify the background color to be used
in the current menu. The COLOR can be specified with one of the
eight canonical strings 'black', 'red', 'cyan' etc. The background
defaults to black.
'foreground COLOR'
This statements is used to specify the foreground color for menu
items. Its value defaults to 'white'. An optional 'bright'
keyword can appear before the actual color.
'border COLOR'
'border' is used to specify the border color for the menu. Its
value defaults to 'white'. An optional 'bright' keyword can appear
before the actual color.
'head COLOR'
'head' is used to specify the foreground color for the title of the
menu. Its value defaults to 'white'. An optional 'bright' keyword
can appear before the actual color.
The following statements belong to the action set.
'STRING f.fgcmd CMDSTRING'
When the mouse button is released above the corresponding menu
item, the CMDSTRING is pasted in the keyboard queue of the current
console. This is not yet implemented.
'STRING f.bgcmd CMDSTRING'
When the mouse button is released above the corresponding menu
item, a shell ('/bin/sh') is forked to execute the specified
command, with 'stdin' connected to '/dev/null', and 'stdout',
'stderr' connected to the active console.
'STRING f.jptty TTYNUMBER'
When the mouse button is released above the corresponding menu
item, the console is switched to the one specified. The TTYNUMBER
must be specified as a string. Any tty can be reached this way,
even those which are not accessible via the keyboard.
'STRING f.mktty TTYNUMBER'
When the mouse button is released above the corresponding menu
item, an unused console is selected, and '/sbin/mingetty' is
executed in it. The current console is switched to the newly
opened console. I use this command to save kernel memory by
opening a single console through '/etc/inittab' and requesting the
others only when i need to login.
'STRING WHOLE-MENU'
A menu can directly follow the label string. When the mouse
pointer leaves the menu frame at the level of STRING, a second menu
is posted on screen.
'STRING f.lock'
When the mouse button is released above the corresponding menu
item, the keyboard and the screen are locked, and only the locking
user or the superuser can unlock them. This is not yet
implemented.
'STRING f.load'
The current loadavg when the menu is posted is concatenated to
STRING to build the actual message displayed on screen. Nothing
happens at button release.
'STRING f.free'
The free memory and swap when the menu is posted is concatenated to
STRING to build the actual message displayed on screen. Nothing
happens at button release.
'STRING f.time'
The current time is formatted with strftime(3), according to
STRING. The resulting string is the actual message displayed on
screen. Nothing happens at button release.
'STRING f.pipe CMDLINE'
When the mouse pointer leaves the menu frame at the level of
STRING, a message box is posted on screen showing the last ten
lines of the output of CMDLINE. CMDLINE is executed by '/bin/sh'.
This is not yet implemented.
'STRING f.nop'
This does nothing, it only displays STRING on the menu.
The 'HOME', 'LOGNAME' and 'USER' environment variables are setup to
the values for the invoking user before spawning an external process
('f.bgcmd', 'f.pipe'). The current directory is always '/'.
Known bugs have been fixed. In particular, if you invoke 'gpm-root'
right after 'gpm', it will delay a few seconds before trying to connect
to the daemon.
Info Catalog
gpm: Emacs Support
gpm: Demo Clients
gpm: hltest