GPM-ROOT(1)                                           GPM-ROOT(1)

NAME
       gpm-root  -  a default handler for gpm, used to draw menus
       on the root window

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-
              ment must follow the option with no  space  betwixt
              (that is, `-V-1' but not `-V -1').  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
       looking at your `/etc/gpm-root.conf'.

       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  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' con-
              nected to `/dev/null', and `stdout', `stderr'  con-
              nected 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/agetty'  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  request-
              ing 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
              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  cmd-
              line. 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 `/'.

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                         1