| 1 |
.TH GPM-ROOT 1 "February 1995" |
| 2 |
.UC 4 |
| 3 |
.SH NAME |
| 4 |
gpm-root \- a default handler for gpm, used to draw menus on |
| 5 |
the root window |
| 6 |
.SH SYNOPSIS |
| 7 |
.B gpm-root |
| 8 |
[ |
| 9 |
.I options |
| 10 |
] |
| 11 |
.br |
| 12 |
.SH DESCRIPTION |
| 13 |
|
| 14 |
.LP |
| 15 |
The program gpm-root is designed to handle Control-Mouse events to |
| 16 |
draw menus on the background of the current tty. The actual menus |
| 17 |
are described by a configuration file in the user's home directory. |
| 18 |
|
| 19 |
.LP |
| 20 |
Please note that gpm-root needs to run with Linux 1.1.73 or |
| 21 |
newer, because previous kernels lack some screen handling capabilities |
| 22 |
required by the program. |
| 23 |
|
| 24 |
.LP |
| 25 |
The program uses the files /dev/vcs* to draw to the console screen. |
| 26 |
These are available only from kernel 1.1.81 onward. If you miss those |
| 27 |
device nodes, you should create them using create_vcs in the |
| 28 |
distribution directory. The tool won't run with kernels older than 1.1.81, |
| 29 |
because they lacked a full screen dump/restore capability. |
| 30 |
|
| 31 |
.LP |
| 32 |
Available command line options are the following: |
| 33 |
.TP |
| 34 |
-m \fBnumber\fP |
| 35 |
Choose the modifier to use (by default: control). The modifier |
| 36 |
can be provided either as a number or as a symbolic string. |
| 37 |
Allowed strings are shift, anyAlt, leftAlt, |
| 38 |
rightAlt, control. |
| 39 |
.TP |
| 40 |
-u |
| 41 |
Deny using user-specific configuration files. With this |
| 42 |
option on, only /etc/gpm/root.conf will be used as a source |
| 43 |
of configuration information. This option |
| 44 |
is intended for those system administrators who fear security could |
| 45 |
be broken by this daemon. Things should be sufficiently secure, but |
| 46 |
if you find a hole please tell me about it. |
| 47 |
.TP |
| 48 |
-D |
| 49 |
Do not automatically enter background operation when started, |
| 50 |
and log messages to the standard error stream, not the syslog |
| 51 |
mechanism. This is useful for debugging; in previous releases |
| 52 |
it was done with a compile-time option. |
| 53 |
.TP |
| 54 |
-V \fBverbosity increment\fP |
| 55 |
Raise the maximum level of messages that will be logged. Thus a |
| 56 |
positive argument has the effect of making the program more |
| 57 |
verbose. One can also give a negative argument to hush the |
| 58 |
program; however, note that due to \fBgetopt(3)\fP rules a negative |
| 59 |
argument must follow the option with no space betwixt (that is, |
| 60 |
-V-1 but not -V -1). Program Arguments,,,libc. |
| 61 |
The argument is optional and its default value is 1. |
| 62 |
|
| 63 |
.LP |
| 64 |
Each time a menu is drawn, the configuration file is reparsed if it has |
| 65 |
changed. This allows modification of personal setup without reinvoking |
| 66 |
the daemon. |
| 67 |
|
| 68 |
.LP |
| 69 |
The actual configuration file is better introduced by looking at your |
| 70 |
/etc/gpm/root.conf. |
| 71 |
.fi |
| 72 |
|
| 73 |
.LP |
| 74 |
The syntax for the file won't be described here, being it quite apparent |
| 75 |
from the example above. Blanks and newlines are unused in parsing the |
| 76 |
file, and the layout of the file is free. Comments are allowed in the |
| 77 |
file: any hash mark (#) found at the beginning of the line or |
| 78 |
after white space makes the parser discard anything up to the next |
| 79 |
line. To insert quotes (") in strings precede them with a backslash. |
| 80 |
|
| 81 |
.LP |
| 82 |
Note that recursive menus are allowed, to any level of recursion. |
| 83 |
|
| 84 |
.LP |
| 85 |
Keywords belong to three groups: the button keyword, the cfg |
| 86 |
keywords and the action keywords. They are all described in the table |
| 87 |
below: |
| 88 |
.TP |
| 89 |
button \fBnumber\fP \fBmenu\fP |
| 90 |
The button keyword is used to introduce a menu. It is |
| 91 |
followed by the number of the relevant button (1=left, |
| 92 |
2=middle, 3=right), an open brace, a menu and a closed brace. |
| 93 |
A menu is made up of cfg statements, followed by |
| 94 |
action statements. Cfg statements can come in any order, |
| 95 |
while the order of action statements tells the actual order |
| 96 |
in which actions will appear on the screen, top to bottom. |
| 97 |
|
| 98 |
.LP |
| 99 |
The following statements belong to the cfg set. |
| 100 |
.TP |
| 101 |
name \fBstring\fP |
| 102 |
If the name keyword is present, the specified |
| 103 |
\fBstring\fP will be used as the name for the current menu. |
| 104 |
.TP |
| 105 |
background \fBcolor\fP |
| 106 |
This statements is used to specify the |
| 107 |
background color to be used in the current menu. The \fBcolor\fP |
| 108 |
can be specified with one of the eight canonical strings black, |
| 109 |
red, cyan etc. The background defaults to black. |
| 110 |
.TP |
| 111 |
foreground \fBcolor\fP |
| 112 |
This statements is used to specify the |
| 113 |
foreground color for menu items. Its value defaults to white. |
| 114 |
An optional bright keyword can appear before the actual color. |
| 115 |
.TP |
| 116 |
border \fBcolor\fP |
| 117 |
border is used to specify the |
| 118 |
border color for the menu. Its value defaults to white. |
| 119 |
An optional bright keyword can appear before the actual color. |
| 120 |
.TP |
| 121 |
head \fBcolor\fP |
| 122 |
head is used to specify the |
| 123 |
foreground color for the title of the menu. Its value defaults |
| 124 |
to white. |
| 125 |
An optional bright keyword can appear before the actual color. |
| 126 |
|
| 127 |
.LP |
| 128 |
The following statements belong to the action set. |
| 129 |
.TP |
| 130 |
\fBstring\fP f.fgcmd \fBcmdstring\fP |
| 131 |
When the mouse button is |
| 132 |
released above the corresponding menu item, the \fBcmdstring\fP is |
| 133 |
pasted in the keyboard queue of the current console. This is |
| 134 |
not yet implemented. |
| 135 |
.TP |
| 136 |
\fBstring\fP f.bgcmd \fBcmdstring\fP |
| 137 |
When the mouse button is released above the |
| 138 |
corresponding menu item, a shell (/bin/sh) is forked to |
| 139 |
execute the specified command, with stdin |
| 140 |
connected to /dev/null, and stdout, stderr connected |
| 141 |
to the active console. |
| 142 |
.TP |
| 143 |
\fBstring\fP f.jptty \fBttynumber\fP |
| 144 |
When the mouse button is |
| 145 |
released above the corresponding menu item, the console is |
| 146 |
switched to the one specified. The \fBttynumber\fP must be specified |
| 147 |
as a string. Any tty can be reached this way, even those which are |
| 148 |
not accessible via the keyboard. |
| 149 |
.TP |
| 150 |
\fBstring\fP f.mktty \fBttynumber\fP |
| 151 |
When the mouse button is |
| 152 |
released above the corresponding menu item, an unused console is |
| 153 |
selected, and /sbin/mingetty is executed in it. The current console |
| 154 |
is switched to the newly opened console. I use this command to save |
| 155 |
kernel memory by opening a single console through /etc/inittab |
| 156 |
and requesting the others only when i need to login. |
| 157 |
.TP |
| 158 |
\fBstring\fP \fBWhole-menu\fP |
| 159 |
A menu can directly follow the label string. |
| 160 |
When the mouse pointer leaves the menu frame at the level of \fBstring\fP, |
| 161 |
a second menu is posted on screen. |
| 162 |
.TP |
| 163 |
\fBstring\fP f.lock |
| 164 |
When the mouse button is |
| 165 |
released above the corresponding menu item, the keyboard and the |
| 166 |
screen are locked, and only the locking user or the superuser |
| 167 |
can unlock them. This is not yet implemented. |
| 168 |
.TP |
| 169 |
\fBstring\fP f.load |
| 170 |
The current loadavg when the menu is posted is concatenated to \fBstring\fP |
| 171 |
to build the actual message displayed on screen. Nothing happens at |
| 172 |
button release. |
| 173 |
.TP |
| 174 |
\fBstring\fP f.free |
| 175 |
The free memory and swap when the menu is posted is concatenated |
| 176 |
to \fBstring\fP |
| 177 |
to build the actual message displayed on screen. Nothing happens at |
| 178 |
button release. |
| 179 |
.TP |
| 180 |
\fBstring\fP f.time |
| 181 |
The current time is formatted with \fBstrftime(3)\fP, according to |
| 182 |
\fBstring\fP. The resulting string is |
| 183 |
the actual message displayed on screen. Nothing happens at |
| 184 |
button release. |
| 185 |
.TP |
| 186 |
\fBstring\fP f.pipe \fBcmdline\fP |
| 187 |
When the mouse pointer leaves the menu frame at the level of \fBstring\fP, |
| 188 |
a message box is posted on screen showing the last ten lines |
| 189 |
of the output of \fBcmdline\fP. \fBcmdline\fP is executed |
| 190 |
by /bin/sh. This is not yet implemented. |
| 191 |
|
| 192 |
|
| 193 |
.TP |
| 194 |
\fBstring\fP f.nop |
| 195 |
This does nothing, it only displays \fBstring\fP on the menu. |
| 196 |
|
| 197 |
.LP |
| 198 |
The HOME, LOGNAME and USER environment variables are setup |
| 199 |
to the values for the invoking user before spawning an external |
| 200 |
process (f.bgcmd, f.pipe). The current directory is always /. |
| 201 |
|
| 202 |
.LP |
| 203 |
.SH BUGS |
| 204 |
|
| 205 |
.LP |
| 206 |
Known bugs have been fixed. In particular, if you invoke gpm-root |
| 207 |
right after gpm, it will delay a few seconds before trying to connect |
| 208 |
to the daemon. |
| 209 |
|
| 210 |
.LP |
| 211 |
.SH AUTHOR |
| 212 |
Alessandro Rubini <[email protected]> |
| 213 |
|
| 214 |
.LP |
| 215 |
.SH FILES |
| 216 |
.nf |
| 217 |
/dev/gpmctl The socket used to connect to gpm. |
| 218 |
/etc/gpm/root.conf The default configuration file. |
| 219 |
$(HOME)/.gpm-root The user configuration file. |
| 220 |
/dev/vcs* Virtual Console Screens |
| 221 |
.fi |
| 222 |
|
| 223 |
.LP |
| 224 |
.SH SEE ALSO |
| 225 |
.nf |
| 226 |
\fB gpm(8) \fP |
| 227 |
|
| 228 |
.fi |
| 229 |
The info file about `gpm', which gives more complete information and |
| 230 |
explains how to write a gpm client. |