gpm-root

GPM-ROOT(1)                 General Commands Manual                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 newwer,
       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. Thigs should be sufficiently secure, but if you find a
              hole please tell me about it.


       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 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/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 requesting the
              others only when i need to login.

       string @{ Whole-menu
              A menu can directly follow the lable 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'. The `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 delasy a few seconds before trying to connect to the
       daemon.


AUTHOR
       Alessandro Rubini <rubini@ipvvis.unipv.it>


FILES
       /var/run/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(1)

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



4th Berkeley Distribution        February 1995                     GPM-ROOT(1)