## SYNOPSIS

           gpm-root [ options ]

## DESCRIPTION

           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  han
           dling capabilities required by the program.

           The  program  uses the files /dev/vcs* to draw to the con
           sole 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 argu

           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
                  When  the mouse button is released above the corre
                  sponding 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  corre
                  sponding  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  corre
                  sponding  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  corre
                  sponding  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 corre
                  sponding 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 con
                  catenated  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
           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 /.

## BUGS

           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.

## AUTHOR

           Alessandro Rubini <rubini@linux.it>

## FILES

           /dev/gpmctl     The socket used to connect to gpm.
           /etc/gpm/root.conf  The default configuration file.
           $(HOME)/.gpm-root   The user configuration file.
           /dev/vcs*           Virtual Console Screens

## SEE ALSO

            gpm(8)

           The  info  file  about  `gpm',  which  gives more complete
           information and explains how to write a gpm client.

                              February 1995               GPM-ROOT(1)